¿Qué es API Pagination? Cursor vs Offset Estrategias

¿Qué es API pagination?

API pagination es la práctica de dividir un result set grande en chunks más pequeños ("páginas") devueltos sobre múltiples requests. Sin paginación, un endpoint que devuelva 1M registros crashearía la base datos, agotaría memoria o time-outearía.

La estrategia paginación correcta depende de shape datos, patrones tráfico y necesidades UX.

Las cuatro estrategias paginación principales

Offset/Limit pagination

GET /api/users?offset=200&limit=50

Pros: Simple implementar; soporta UX jump-to-page.

Cons: Lento en offsets grandes; inconsistente si datos cambian.

SELECT * FROM users ORDER BY created_at LIMIT 50 OFFSET 200;

Cursor-based pagination

GET /api/users?cursor=eyJpZCI6MTIzNDV9&limit=50

Pros: Estable a través cambios datos; rápido; ideal para infinite scroll.

Cons: No jump-to-page; cursor es opaco.

Keyset (seek) pagination

GET /api/users?after_id=12345&limit=50

Pros: Misma velocidad que cursor; API más simple; estable.

SELECT * FROM users WHERE id > 12345 ORDER BY id LIMIT 50;

Comparación performance

Keyset es tiempo constante.

Patterns paginación API comunes

Link header (RFC 5988)

Link: <https://api.example.com/users?offset=50&limit=50>; rel="next"

Metadata paginación en body response

{
  "data": [...],
  "pagination": {
    "total": 1000,
    "page": 5,
    "per_page": 50
  }
}

Mejores prácticas paginación

• Default + max limit.
• Keyset sobre offset para datasets grandes.
• Sort estable.
• Indexar sort key.
• Documentar estrategia.
• Skip total counts a escala.
• Cachear página 1.
• Considerar streaming.

Pitfalls comunes paginación

• Páginas profundas lentas.
• Resultados inconsistentes.
• Items missing durante paginación.
• Total count a escala.
• Sin max limit.
• Números página en URL forever.

FAQ: API pagination

¿Debería usar offset o cursor pagination?

Cursor para cualquier cosa con >1000 registros o feeds live.

¿Cómo implemento cursor pagination?

Encodear sort key del último item como base64 JSON.

¿Cómo obtengo total count con cursor pagination?

Query COUNT(*) separada, o skip total enteramente.

¿Cuál es el max page size que debería soportar?

Depende del payload. Típico: 100-1000.

¿Pagination params en query string o body?

Query string para GET; body aceptable para POST.

¿Necesito ambos cursors next y prev?

Forward-only suele ser suficiente.

¿Cómo maneja GraphQL paginación?

Spec Relay Cursor Connections.

Load testea APIs paginadas con LoadFocus

Bugs perf paginación solo aparecen bajo tráfico real. LoadFocus corre scripts JMeter y k6 que pegan páginas profundas con concurrencia realista desde 25+ regiones. Regístrate en loadfocus.com/signup.