Explorar guías rápidas · APIs
Patrones de paginación de API
Diseña y consume APIs paginadas de forma segura con los patrones de offset, número de página, cursor, keyset y token de continuación, con un orden claro, un recorrido estable y un comportamiento del cliente seguro en producción.
En esta página
- Problema
- Respuesta rápida
- Código / comandos
- 1. Paginación solo con límite
- 2. Paginación por offset
- 3. Paginación por número de página
- 4. Devolver metadatos de paginación
- 5. Ten cuidado con los totales
- 6. Paginación por cursor
- 7. Hacer que los cursores sean opacos para los clientes
- 8. El contenido del cursor puede codificar el estado del orden
- 9. Paginación keyset
- 10. Usar un criterio de desempate determinista
- 11. Ajustar el predicado keyset a la dirección del orden
- 12. Paginación keyset compuesta
- 13. No expongas offsets de filas de la base de datos como cursor de negocio estable
- 14. La paginación por offset puede saltarse filas durante inserciones concurrentes
- 15. La paginación por offset puede duplicar filas durante eliminaciones
- 16. La paginación keyset suele ser más estable para el recorrido hacia delante
- 17. La paginación por cursor no crea automáticamente una instantánea
- 18. Añadir un límite superior estable para recorridos largos
- 19. Paginación por token de continuación
- 20. Los tokens de continuación pueden caducar
- 21. Vincular los cursores a la forma de la consulta original
- 22. Codificar la identidad de filtros y orden en los cursores opacos cuando sea útil
- 23. Firmar los cursores cuando los clientes no deban manipularlos
- 24. Cifrar los cursores solo cuando se necesite confidencialidad
- 25. Validar el tamaño de página
- 26. Limitar o rechazar solicitudes de páginas demasiado grandes
- 27. No cambiar el tamaño de página en silencio sin avisar al cliente
- 28. Conservar los filtros entre páginas
- 29. Conservar el orden entre páginas
- 30. Paginar después de filtrar, no antes
- 31. Paginar sobre una granularidad de negocio estable
- 32. Evitar paginar una consulta no determinista
- 33. No confiar nunca en el orden físico de las filas en la base de datos
- 34. Usar también un orden único para la paginación hacia atrás
- 35. Ejemplo de respuesta con cursor hacia delante
- 36. Ejemplo de pageInfo con soporte para recorrido hacia atrás
- 37. Paginación basada en enlaces
- 38. Paginación con el encabezado HTTP Link
- 39. Bucle de cliente para paginación por cursor
- 40. No detenerse basándose solo en la longitud de la página
- 41. Bucle de cliente con offset
- 42. Reintentar una página sin avanzar el estado
- 43. Hacer idempotente el procesamiento de páginas cuando sea posible
- 44. No suponer una entrega exactly-once a partir de la paginación
- 45. Guardar el checkpoint del token de continuación solo después de un procesamiento duradero
- 46. Almacenar los checkpoints de cursor junto con la identidad de la consulta
- 47. La caducidad de los cursores requiere una estrategia de reinicio
- 48. Usar watermarks para la sincronización incremental
- 49. Añadir un criterio de desempate a la sincronización por watermark
- 50. Usar con cuidado límites incrementales semiabiertos
- 51. Evitar updated_at > last_timestamp sin manejo de empates
- 52. La paginación por offset puede volverse más lenta con offsets profundos
- 53. La paginación keyset funciona mejor con índices adecuados
- 54. Evitar joins grandes después de paginar si cambian la multiplicidad de filas
- 55. Evitar paginar después de multiplicar filas
- 56. Devolver la última página vacía de forma coherente
- 57. Un cursor no válido debe ser un error del cliente
- 58. No exponer stack traces cuando falla la decodificación del cursor
- 59. Los límites de tasa se aplican a toda la paginación
- 60. Las cadenas de cursores secuenciales suelen ser secuenciales por naturaleza
- 61. Paralelizar por partición, no adivinando cursores
- 62. El tamaño de página afecta al rendimiento y al costo de los fallos
- 63. Comprimir las respuestas paginadas grandes
- 64. Limitar los campos cuando esté admitido
- 65. Evitar devolver colecciones anidadas enormes dentro de cada elemento paginado
- 66. La paginación y la ordenación deben ser compatibles
- 67. Rechazar los campos de ordenación no admitidos
- 68. Validar las entradas numéricas de paginación
- 69. Evitar el desbordamiento de enteros al calcular el offset
- 70. Usar un orden predeterminado estable
- 71. Tener en cuenta el comportamiento ante eliminaciones
- 72. Tener en cuenta las actualizaciones de las claves de ordenación
- 73. Preferir claves monótonas inmutables para feeds de tipo stream
- 74. Los UUID son únicos, pero no necesariamente útiles como claves de ordenación
- 75. La paginación no sustituye a la exportación masiva
- 76. Usar 202 para la creación de exportaciones asíncronas
- 77. Documentar la consistencia de las páginas
- 78. Documentar el ciclo de vida de los cursores
- 79. Monitorear el comportamiento de la paginación
- 80. Detectar usos patológicos del offset
- Qué significa el resultado
- Qué revisar
- Registros duplicados entre páginas
- Registros faltantes
- Las páginas profundas se vuelven más lentas
- El cursor deja de ser válido de repente
- El cliente entra en un bucle infinito
- El cliente se detiene antes de tiempo
- Notas de producción
- La semántica de paginación forma parte del contrato de la API
- El orden determinista es obligatorio
- Los valores de cursor deberían ser, en general, opacos
- La paginación no garantiza consistencia de instantánea
- Los reintentos y los checkpoints importan
- La extracción masiva puede requerir otra API
- Errores comunes
- 1. Paginar sin ORDER BY
- 2. Ordenar solo por una marca de tiempo no única
- 3. Usar por defecto paginación por offset en conjuntos de datos enormes y mutables
- 4. Suponer que la paginación por cursor crea una instantánea
- 5. Dejar que los clientes elijan un tamaño de página ilimitado
- 6. Avanzar el cursor antes de que el procesamiento de la página sea duradero
- 7. Suponer que las páginas cortas significan el final de los datos
- 8. Reutilizar un cursor con filtros u orden diferentes
- 9. Devolver totales exactos cuando son demasiado costosos
- 10. Usar la paginación para exportaciones masivas de datos
- Siguiente paso
- Para profundizar
Problema
Un endpoint de API puede devolver demasiados datos para enviarlos en una sola respuesta.
La paginación resuelve el problema de transporte, pero aparecen incidencias en producción cuando los ingenieros no definen:
- el orden
- los límites de página
- el comportamiento mientras los datos cambian
- la semántica de continuación
- el tamaño máximo de página
- el comportamiento de los reintentos
- el manejo de filas duplicadas y faltantes
- cómo saben los clientes que han terminado
El objetivo es elegir un modelo de paginación que se ajuste a los datos y hacer que el recorrido sea predecible tanto para quienes producen la API como para quienes la consumen.
Respuesta rápida
Usa este modelo de decisión:
API de administración pequeña/sencilla
→ el número de página o el offset pueden bastar
Conjunto de datos grande y ordenado
→ paginación por cursor o keyset
Conjunto de datos que cambia rápidamente
→ cursor/keyset con orden determinista
El backend/proveedor ya devuelve tokens de continuación
→ exponer o encapsular la semántica de tokens de continuación
Se necesita acceso directo a la «página 57»
→ paginación por página/offset
Se necesita un recorrido secuencial eficiente
→ paginación por cursor/keyset
Ejemplo sencillo con offset:
GET /v1/orders?limit=100&offset=200
Ejemplo con cursor:
GET /v1/orders?limit=100&after=eyJpZCI6MTIzNDU2fQ
Ejemplo con keyset:
GET /v1/orders?limit=100&after_created_at=2026-10-04T14:00:00Z&after_id=123456
La regla más importante es:
la paginación requiere un orden determinista
Código / comandos
1. Paginación solo con límite
Ejemplo:
GET /v1/orders?limit=100
Esto está incompleto a menos que la API defina también:
- el orden
- el mecanismo de continuación
- el límite máximo
Un límite por sí solo no es un contrato de paginación completo.
2. Paginación por offset
GET /v1/orders?limit=100&offset=200
Forma SQL equivalente:
SELECT
order_id,
created_at,
amount
FROM dbo.orders
ORDER BY created_at, order_id
OFFSET 200 ROWS
FETCH NEXT 100 ROWS ONLY;
Úsala cuando:
- el volumen de datos es moderado
- importa el acceso directo a páginas concretas
- la modificación del conjunto de datos durante el recorrido no es una preocupación importante
3. Paginación por número de página
GET /v1/orders?page=3&pageSize=100
Normalmente el servidor hace la conversión:
offset = (page - 1) * pageSize
Es fácil de entender para los clientes.
Tiene las mismas limitaciones fundamentales de consistencia y rendimiento que la paginación por offset.
4. Devolver metadatos de paginación
Ejemplo de respuesta:
{
"items": [
{
"orderId": 123
}
],
"page": 3,
"pageSize": 100,
"hasNext": true
}
Devuelve totalCount solo cuando puedas calcularlo con un costo aceptable y su semántica sea clara.
5. Ten cuidado con los totales
Este patrón:
{
"totalCount": 98765432
}
puede requerir un conteo costoso sobre todo el conjunto de datos filtrado.
No prometas un total exacto si generarlo encarece cada solicitud.
Alternativas:
hasNext
nextCursor
approximateCount
conteo devuelto por un endpoint independiente
si son adecuadas para el producto.
6. Paginación por cursor
Solicitud:
GET /v1/orders?limit=100&after=opaque-cursor-value
Respuesta:
{
"items": [
{
"orderId": 123
}
],
"nextCursor": "opaque-cursor-value-2",
"hasNext": true
}
Úsala cuando los clientes avanzan principalmente de forma secuencial.
7. Hacer que los cursores sean opacos para los clientes
Prefiere:
after=eyJjcmVhdGVkQXQiOiIyMDI2LTEwLTA0VDE0OjAwOjAwWiIsImlkIjoxMjM0NTZ9
en lugar de obligar al cliente a entender las claves de almacenamiento internas.
Un cursor opaco le da al servidor margen para cambiar la implementación más adelante.
8. El contenido del cursor puede codificar el estado del orden
Conceptualmente, un cursor podría representar:
{
"createdAt": "2026-10-04T14:00:00Z",
"orderId": 123456
}
El cliente debe tratarlo como opaco.
El servidor puede codificarlo o firmarlo según corresponda.
9. Paginación keyset
Solicitud:
GET /v1/orders?limit=100&afterCreatedAt=2026-10-04T14:00:00Z&afterId=123456
Condición de estilo SQL:
WHERE
created_at > @after_created_at
OR (
created_at = @after_created_at
AND order_id > @after_id
)
ORDER BY
created_at,
order_id
Así se evita recorrer y descartar un offset grande.
10. Usar un criterio de desempate determinista
Mal:
ORDER BY created_at
si muchas filas comparten la misma marca de tiempo.
Mejor:
ORDER BY
created_at,
order_id
La última columna de ordenación debe hacer que el orden de las filas sea determinista.
11. Ajustar el predicado keyset a la dirección del orden
Ascendente:
WHERE
created_at > @last_created_at
OR (
created_at = @last_created_at
AND order_id > @last_order_id
)
ORDER BY
created_at ASC,
order_id ASC
Descendente:
WHERE
created_at < @last_created_at
OR (
created_at = @last_created_at
AND order_id < @last_order_id
)
ORDER BY
created_at DESC,
order_id DESC
Los operadores de comparación deben coincidir con la dirección de ordenación solicitada.
12. Paginación keyset compuesta
Si el orden es:
tenant_id
created_at
order_id
el predicado de continuación debe preservar el mismo orden lexicográfico.
No pagines usando solo una parte de la clave de ordenación.
13. No expongas offsets de filas de la base de datos como cursor de negocio estable
Un offset identifica una posición en un orden de resultados concreto y en un momento concreto.
No es un identificador estable.
Si se insertan o eliminan filas, los offsets posteriores pueden desplazarse.
14. La paginación por offset puede saltarse filas durante inserciones concurrentes
Ejemplo:
Página 1:
filas 1–100
nueva fila insertada cerca del principio
Página 2:
OFFSET 100
El cliente puede ver:
- una fila duplicada
- una fila omitida
según cómo se haya desplazado el orden.
15. La paginación por offset puede duplicar filas durante eliminaciones
Si desaparecen filas anteriores entre solicitudes, los offsets se desplazan hacia atrás.
Esto puede hacer que la siguiente solicitud se solape con filas ya devueltas.
Es el comportamiento esperado en conjuntos de datos mutables.
16. La paginación keyset suele ser más estable para el recorrido hacia delante
Si el cursor representa la última clave ordenada vista:
created_at + order_id
las filas nuevas insertadas antes de esa clave normalmente no desplazan el punto de continuación.
Esto hace que la paginación por cursor/keyset resulte atractiva para conjuntos de datos mutables.
17. La paginación por cursor no crea automáticamente una instantánea
Incluso con cursores, los datos subyacentes pueden cambiar entre solicitudes.
Si se requiere una semántica estricta de instantánea (snapshot), necesitas un diseño explícito, por ejemplo:
- un identificador de instantánea/versión
- un límite superior fijo
- semántica de instantánea/transacción de la base de datos
- un conjunto de resultados exportado
No prometas consistencia de instantánea a menos que el backend realmente la proporcione.
18. Añadir un límite superior estable para recorridos largos
Ejemplo de primera solicitud:
GET /v1/events?limit=100
El servidor puede establecer:
snapshotMaxId = 9000000
El resto del recorrido puede aplicar:
event_id <= 9000000
Esto impide que los eventos nuevos amplíen indefinidamente el conjunto de datos durante el mismo recorrido.
Úsalo solo si encaja con la semántica del producto.
19. Paginación por token de continuación
Algunos servicios devuelven un token opaco generado por el proveedor:
{
"items": [...],
"continuationToken": "abc123"
}
Siguiente solicitud:
GET /v1/items?continuationToken=abc123
Trata el token como opaco.
No lo analices ni lo modifiques a menos que el proveedor documente explícitamente su estructura.
20. Los tokens de continuación pueden caducar
Documenta si un token es:
- de corta duración
- reutilizable
- de un solo uso
- vinculado a los filtros
- vinculado a la identidad de quien llama
Los clientes no deben suponer que un token de continuación funciona para siempre.
21. Vincular los cursores a la forma de la consulta original
Si un cursor se generó para:
status=active
sort=created_at
no permitas que el cliente lo reutilice con:
status=closed
sort=name
El servidor debe rechazar o ignorar las combinaciones de cursor y consulta incompatibles.
22. Codificar la identidad de filtros y orden en los cursores opacos cuando sea útil
Conceptualmente:
{
"sort": "created_at,id",
"filtersHash": "abc123",
"lastCreatedAt": "...",
"lastId": 123
}
Esto puede evitar el uso indebido de un cursor con una consulta diferente.
No expongas valores de filtro sensibles sin necesidad.
23. Firmar los cursores cuando los clientes no deban manipularlos
Un cursor controlado por el servidor puede ser:
datos útiles
+
firma de integridad
de modo que se rechace cualquier contenido de cursor modificado.
No confíes en la codificación Base64 como protección contra manipulaciones.
Codificar no es firmar.
24. Cifrar los cursores solo cuando se necesite confidencialidad
Si el contenido del cursor incluye identificadores internos o estado sensible que no debería ser visible, el cifrado puede ser apropiado.
Si no se necesita confidencialidad, una codificación opaca firmada puede bastar.
Usa bibliotecas o frameworks criptográficos consolidados.
25. Validar el tamaño de página
Ejemplo de política:
default = 100
max = 1000
No supongas que estos valores son correctos en todos los casos.
Elígelos en función de:
- el ancho de las filas
- el costo en el backend
- la latencia
- el comportamiento de los clientes
- los límites de tasa
26. Limitar o rechazar solicitudes de páginas demasiado grandes
Ejemplo:
GET /v1/orders?limit=1000000
La API no debe aceptar a ciegas tamaños de página arbitrarios.
O bien:
rechazar con un error de validación
o bien:
limitar al máximo documentado
Sé coherente.
27. No cambiar el tamaño de página en silencio sin avisar al cliente
Si el cliente pide:
limit=1000
y el servidor lo limita a:
500
haz visible el tamaño de página real en:
- los metadatos de la respuesta
- la documentación
- los encabezados
para que el cliente pueda razonar correctamente.
28. Conservar los filtros entre páginas
El código del cliente debe enviar el mismo conjunto de filtros en cada página.
Mal:
Página 1:
status=active
Página 2:
status omitido
Esto cambia el conjunto de resultados a mitad del recorrido.
29. Conservar el orden entre páginas
Un cursor generado con:
sort=created_at
no debe reutilizarse con:
sort=name
El orden forma parte del estado de paginación.
30. Paginar después de filtrar, no antes
Orden conceptual correcto:
filtrar
→ ordenar
→ paginar
No:
paginar
→ filtrar
De lo contrario, los tamaños de página y la semántica del recorrido dejan de ser correctos.
31. Paginar sobre una granularidad de negocio estable
Si un join produce varias filas por pedido pero la API promete un pedido por elemento, deduplica o agrega a la granularidad de pedido prevista antes de paginar.
No pagines sobre una granularidad intermedia accidental.
32. Evitar paginar una consulta no determinista
SQL incorrecto:
SELECT *
FROM dbo.orders
OFFSET 0 ROWS
FETCH NEXT 100 ROWS ONLY;
sin ORDER BY.
La paginación requiere un orden estable.
33. No confiar nunca en el orden físico de las filas en la base de datos
Una tabla de base de datos no tiene un orden natural garantizado a menos que la consulta especifique uno.
Define siempre ORDER BY.
34. Usar también un orden único para la paginación hacia atrás
Si admites:
before=<cursor>
el servidor debe invertir correctamente el predicado de continuación y, aun así, devolver los elementos en el orden de visualización documentado.
La paginación hacia atrás es más compleja que simplemente sustituir > por <.
35. Ejemplo de respuesta con cursor hacia delante
{
"items": [
{
"orderId": 123,
"createdAt": "2026-10-04T14:00:00Z"
}
],
"pageInfo": {
"hasNextPage": true,
"nextCursor": "opaque-token"
}
}
Mantén nombres de metadatos coherentes entre endpoints.
36. Ejemplo de pageInfo con soporte para recorrido hacia atrás
{
"items": [...],
"pageInfo": {
"hasNextPage": true,
"hasPreviousPage": true,
"nextCursor": "next-token",
"previousCursor": "previous-token"
}
}
Expón el recorrido hacia atrás solo si la implementación lo admite correctamente.
37. Paginación basada en enlaces
Una API puede devolver URLs directamente:
{
"items": [...],
"links": {
"next": "https://api.example.com/v1/orders?cursor=abc",
"prev": null
}
}
Esto reduce la lógica de construcción de URLs que necesitan los clientes.
38. Paginación con el encabezado HTTP Link
Ejemplo:
Link: <https://api.example.com/v1/orders?cursor=abc>; rel="next"
Es válido y útil en algunas APIs.
No obligues a los clientes a analizar tanto la paginación en el cuerpo como los encabezados Link a menos que haya una razón clara.
39. Bucle de cliente para paginación por cursor
Ejemplo en Python:
import requests
url = "https://api.example.com/v1/orders"
cursor = None
while True:
params = {
"limit": 100
}
if cursor:
params["after"] = cursor
response = requests.get(
url,
params=params,
timeout=30,
)
response.raise_for_status()
payload = response.json()
for item in payload["items"]:
process(item)
cursor = payload.get("nextCursor")
if not cursor:
break
En producción, añade reintentos, autenticación, logging y procesamiento idempotente según corresponda.
40. No detenerse basándose solo en la longitud de la página
Lógica de cliente incorrecta:
if len(items) < page_size:
break
Esto puede fallar si la API:
- filtra internamente
- limita los resultados de forma dinámica
- devuelve páginas dispersas
- usa continuación del lado del proveedor
Prefiere indicadores explícitos:
nextCursor
hasNext
nextLink
del contrato de la API.
41. Bucle de cliente con offset
import requests
offset = 0
limit = 100
while True:
response = requests.get(
"https://api.example.com/v1/orders",
params={
"offset": offset,
"limit": limit,
},
timeout=30,
)
response.raise_for_status()
payload = response.json()
items = payload["items"]
for item in items:
process(item)
if not payload.get("hasNext"):
break
offset += limit
Úsalo solo si la API garantiza este modelo de paginación.
42. Reintentar una página sin avanzar el estado
Comportamiento correcto del cliente:
solicitar la página
→ fallo
→ reintentar la misma página/el mismo cursor
→ éxito
→ procesar de forma segura
→ avanzar el cursor
No avances el token de continuación antes de que la página se haya procesado correctamente.
43. Hacer idempotente el procesamiento de páginas cuando sea posible
Si el cliente falla tras procesar media página y reintenta esa página, puede volver a ver registros.
Diseña el procesamiento para que una entrega duplicada no corrompa el estado aguas abajo.
Ejemplos:
- upsert por clave de negocio
- checkpoint después de un procesamiento duradero
- deduplicación por ID de evento
44. No suponer una entrega exactly-once a partir de la paginación
La paginación es un mecanismo de recuperación de datos.
No garantiza que un cliente observe cada registro mutable exactamente una vez ante fallos, reintentos o cambios concurrentes.
Si importa un comportamiento de negocio similar a exactly-once, añade estado duradero e idempotencia.
45. Guardar el checkpoint del token de continuación solo después de un procesamiento duradero
Mal:
guardar nextCursor
→ procesar la página
→ fallo
La página puede saltarse tras el reinicio.
Más seguro:
obtener la página
→ procesar la página de forma duradera
→ guardar nextCursor/el checkpoint
46. Almacenar los checkpoints de cursor junto con la identidad de la consulta
Checkpoint:
{
"endpoint": "/v1/orders",
"filters": {
"status": "active"
},
"cursor": "opaque-token"
}
No reutilices un cursor almacenado para una forma de consulta diferente.
47. La caducidad de los cursores requiere una estrategia de reinicio
Si los cursores pueden caducar, los clientes deben saber si deben:
- reiniciar el recorrido
- reiniciar desde la última clave de negocio procesada
- solicitar una exportación nueva
- usar en su lugar un watermark duradero
Documenta este comportamiento.
48. Usar watermarks para la sincronización incremental
Ejemplo:
updated_at > last_successful_watermark
La paginación y la carga incremental resuelven problemas diferentes.
Una sincronización robusta suele combinar:
filtro incremental
+
paginación determinista
49. Añadir un criterio de desempate a la sincronización por watermark
Mal:
updated_at > 2026-10-04T14:00:00Z
si muchas filas comparten esa marca de tiempo.
Mejor estado de continuación:
updated_at
+
id
con semántica keyset.
50. Usar con cuidado límites incrementales semiabiertos
Un patrón habitual es:
inicio inclusivo
fin exclusivo
Ejemplo:
updated_at >= start
AND updated_at < end
Esto puede simplificar los límites entre lotes adyacentes.
En una sincronización incremental paginada, define aun así un orden determinista de las filas dentro de la ventana.
51. Evitar updated_at > last_timestamp sin manejo de empates
Si varios registros tienen:
updated_at = last_timestamp
algunos pueden saltarse tras un reinicio.
Almacena suficiente estado para distinguir las filas que comparten la misma marca de tiempo.
52. La paginación por offset puede volverse más lenta con offsets profundos
Conceptualmente:
OFFSET 10
→ relativamente barato
OFFSET 10,000,000
→ la base de datos puede seguir teniendo que localizar/recorrer/ordenar muchísimas filas previas
El comportamiento exacto depende de la base de datos, los índices y el plan de consulta.
No supongas un acceso a páginas en tiempo constante.
53. La paginación keyset funciona mejor con índices adecuados
Para:
ORDER BY created_at, order_id
un índice útil suele empezar por columnas de ordenación/filtro compatibles.
El diseño de índices depende de:
- los filtros
- la selectividad
- las columnas incluidas
- el motor de base de datos
No añadas un índice a ciegas solo porque exista paginación.
54. Evitar joins grandes después de paginar si cambian la multiplicidad de filas
Flujo conceptual problemático:
paginar pedidos
→ hacer join con order_lines
→ el resultado tiene ahora varias filas por pedido
Si el contrato de la API es un pedido por elemento, enriquece con cuidado o agrega las líneas por separado.
55. Evitar paginar después de multiplicar filas
Si un join crea duplicados accidentalmente antes de paginar, los límites de página se vuelven inestables y los conteos, engañosos.
Valida la granularidad antes de paginar.
56. Devolver la última página vacía de forma coherente
Si un cursor solicita explícitamente datos más allá del final, elige un comportamiento documentado, por ejemplo:
{
"items": [],
"nextCursor": null,
"hasNext": false
}
No alternes al azar entre un 200 vacío y un 404.
57. Un cursor no válido debe ser un error del cliente
Si un cursor está mal formado, manipulado, caducado o es incompatible con la solicitud, devuelve un error claro dirigido al cliente.
Ejemplo:
HTTP/1.1 400 Bad Request
{
"error": "invalid_cursor",
"message": "The pagination cursor is invalid or expired."
}
El modelo exacto de estado y error debe ser coherente con el resto de la API.
58. No exponer stack traces cuando falla la decodificación del cursor
Los cursores mal formados son entrada del cliente, no una excusa para filtrar detalles internos de análisis o criptografía.
Devuelve un error de dominio estable.
59. Los límites de tasa se aplican a toda la paginación
Los clientes pueden obtener cientos de páginas.
Respeta:
429Retry-After- las cuotas por cliente
- los límites de concurrencia
No paralelices automáticamente todas las solicitudes de páginas.
60. Las cadenas de cursores secuenciales suelen ser secuenciales por naturaleza
Si la página N+1 necesita el cursor de la página N:
página 1
→ cursor 2
→ página 2
→ cursor 3
no puedes solicitar todas las páginas en paralelo de forma segura a menos que la API exponga particiones/rangos independientes.
61. Paralelizar por partición, no adivinando cursores
Si la API admite un particionamiento como:
tenant
rango de fechas
shard
clave de partición
los clientes pueden procesar particiones independientes de forma concurrente.
No inventes valores de cursor futuros.
62. El tamaño de página afecta al rendimiento y al costo de los fallos
Páginas más grandes:
menos solicitudes HTTP
payloads más grandes
más trabajo de reintento si falla una página
más memoria por respuesta
Páginas más pequeñas:
más solicitudes
más sobrecarga por solicitud
unidad de reintento más pequeña
Elige en función de las características reales de la carga de trabajo.
63. Comprimir las respuestas paginadas grandes
Si está admitido, los clientes pueden enviar:
Accept-Encoding: gzip
o usar:
curl --compressed ...
Esto puede reducir el volumen transferido en JSON con mucho texto.
64. Limitar los campos cuando esté admitido
Ejemplo:
GET /v1/orders?fields=orderId,createdAt,amount&limit=100
Reducir el ancho de las filas puede mejorar el rendimiento de la paginación.
Expón la proyección de campos solo si el contrato de tu API la admite de forma segura.
65. Evitar devolver colecciones anidadas enormes dentro de cada elemento paginado
Ejemplo:
100 pedidos
×
miles de líneas de pedido anidadas
puede anular el propósito de la paginación.
Considera:
- endpoints hijos independientes
- resúmenes
- expansiones acotadas
- parámetros de inclusión explícitos
66. La paginación y la ordenación deben ser compatibles
Si los clientes pueden ordenar por columnas arbitrarias:
?sort=name
el servidor necesita un criterio de desempate determinista para cada ordenación admitida.
Ejemplo:
sort=name
orden efectivo:
name, id
67. Rechazar los campos de ordenación no admitidos
No interpoles directamente en el SQL expresiones de ordenación arbitrarias proporcionadas por el cliente.
Usa una lista blanca de campos y direcciones admitidos.
Es una cuestión tanto de corrección como de seguridad.
68. Validar las entradas numéricas de paginación
Ejemplos de solicitudes no válidas:
limit=-1
offset=-50
page=0
pageSize=999999999
Devuelve un error de validación controlado.
No permitas que valores no válidos lleguen sin comprobar al código de almacenamiento.
69. Evitar el desbordamiento de enteros al calcular el offset
En APIs por número de página:
offset = (page - 1) * pageSize
valida los límites antes de calcular o ejecutar valores muy grandes.
Esto importa especialmente en lenguajes de servidor fuertemente tipados y en APIs públicas grandes.
70. Usar un orden predeterminado estable
Si el cliente no especifica el orden, documenta el orden predeterminado del servidor.
Ejemplo:
created_at DESC, id DESC
No cambies el orden predeterminado en silencio entre versiones.
71. Tener en cuenta el comportamiento ante eliminaciones
Con paginación keyset:
última clave vista
→ continuar después de esa clave
eliminar una fila anterior normalmente no desplaza el cursor.
Con paginación por offset, una eliminación puede desplazar las posiciones siguientes.
Esta es una de las razones por las que la paginación keyset suele ser más estable con datos mutables.
72. Tener en cuenta las actualizaciones de las claves de ordenación
Si la columna de ordenación de una fila cambia mientras el cliente recorre los datos, la fila puede moverse:
antes del cursor
o
después del cursor
y podría omitirse u observarse dos veces.
Si esto importa, usa:
- una clave de ordenación inmutable
- un límite de instantánea
- una secuencia de solo inserción (append-only)
- un diseño dedicado de sincronización/feed de cambios
73. Preferir claves monótonas inmutables para feeds de tipo stream
Ejemplos:
event_id
sequence_number
commit_position
cuando estén disponibles.
Simplifican el recorrido keyset y los checkpoints.
No inventes una semántica monótona para identificadores que en realidad no están ordenados.
74. Los UUID son únicos, pero no necesariamente útiles como claves de ordenación
Un UUID aleatorio puede ser un excelente identificador único, pero una mala clave de paginación cronológica.
Úsalo como criterio de desempate si hace falta, no como sustituto de un orden con significado, a menos que su semántica de orden sea intencionada.
75. La paginación no sustituye a la exportación masiva
Si un cliente necesita:
cientos de millones de filas
considera:
- un trabajo de exportación asíncrono
- la entrega de archivos
- el almacenamiento de objetos
- un mecanismo de uso compartido de datos
en lugar de forzar millones de llamadas de páginas a la API.
76. Usar 202 para la creación de exportaciones asíncronas
Ejemplo:
POST /v1/exports
Respuesta:
HTTP/1.1 202 Accepted
Location: /v1/exports/job-123
Después, el cliente puede consultar periódicamente el estado o recibir una notificación cuando la exportación esté lista.
77. Documentar la consistencia de las páginas
Indica a los clientes si la paginación es:
de mejor esfuerzo sobre datos en vivo
consistente con una instantánea
acotada por el watermark de la primera solicitud
eventualmente consistente
No dejes sin definir el comportamiento ante cambios en integraciones críticas.
78. Documentar el ciclo de vida de los cursores
Incluye:
¿opaco?
¿caducidad?
¿reutilizable?
¿vinculado a filtros?
¿vinculado a quien llama?
¿solo hacia delante?
Esto evita que los clientes construyan supuestos inseguros.
79. Monitorear el comportamiento de la paginación
Métricas útiles:
solicitudes por endpoint
tamaño de página
offset más profundo
páginas por recorrido
errores de cursor
tasa de 429
bytes de respuesta
latencia por tamaño de página
Pueden revelar clientes que abusan de offsets grandes o que obtienen conjuntos de datos completos de forma ineficiente.
80. Detectar usos patológicos del offset
Ejemplo:
offset=50,000,000
puede indicar que el cliente usa un endpoint de listado como mecanismo de exportación masiva.
Considera en su lugar un cursor o una API de exportación.
Qué significa el resultado
| Patrón | Fortaleza | Debilidad |
|---|---|---|
| Número de página | Fácil para personas/interfaces | Mismos problemas de offset profundo y cambios que el offset |
| Offset + límite | Sencillo, admite acceso directo | Puede volverse lento e inestable con conjuntos de datos cambiantes |
| Cursor | Abstracción de API estable | Normalmente secuencial; hay que definir el ciclo de vida del token |
| Keyset | Recorrido hacia delante eficiente y estable | Acceso directo más difícil; requiere una clave determinista |
| Token de continuación | Funciona bien con la paginación nativa del proveedor/backend | A menudo opaco/específico del proveedor |
| Instantánea + cursor | Fuerte consistencia del recorrido | Más complejidad/estado en el backend |
| Exportación asíncrona | Lo mejor para recuperaciones muy grandes | No sirve para navegar páginas de forma interactiva |
La decisión de diseño central es:
acceso directo a páginas
frente a
recorrido estable y eficiente
Qué revisar
Registros duplicados entre páginas
Revisa:
- paginación por offset sobre datos cambiantes
- orden no único
- actualizaciones de claves de ordenación
- comportamiento de los reintentos
Registros faltantes
Revisa:
- el predicado del cursor
- los empates de marcas de tiempo
- un orden inestable
- el momento del checkpoint
- cambios de filtros entre solicitudes
Las páginas profundas se vuelven más lentas
La paginación por offset puede estar recorriendo/saltando prefijos cada vez más grandes.
Inspecciona los planes de consulta y considera la paginación keyset.
El cursor deja de ser válido de repente
Revisa:
- la caducidad
- cambios de filtros/orden
- las claves de firma de los tokens
- las reglas de continuación del backend/proveedor
El cliente entra en un bucle infinito
Revisa:
- el mismo cursor repetido
- la lógica de
hasNext - un servidor que devuelve tokens de continuación que no avanzan
- un cliente que no guarda el nuevo cursor en su checkpoint
El cliente se detiene antes de tiempo
Comprueba si supone erróneamente que:
items.length < tamaño de página solicitado
significa el final.
Prefiere metadatos de continuación explícitos.
Notas de producción
La semántica de paginación forma parte del contrato de la API
Cambiar:
el orden predeterminado
la estructura del cursor
el tope del tamaño de página
el comportamiento de continuación
puede romper a los clientes.
Trata estos aspectos como comportamiento versionado.
El orden determinista es obligatorio
Todo resultado paginado necesita un orden completo.
Si la columna de ordenación visible no es única, añade un criterio de desempate.
Los valores de cursor deberían ser, en general, opacos
Esto reduce el acoplamiento de los clientes con las claves de almacenamiento internas y permite que la implementación evolucione.
La paginación no garantiza consistencia de instantánea
Si la consistencia estricta importa, impleméntala de forma explícita.
Los reintentos y los checkpoints importan
Un cliente robusto debe poder reintentar una página sin:
- saltarse datos
- corromper el estado aguas abajo
La extracción masiva puede requerir otra API
La paginación es ideal para recorridos interactivos acotados, no siempre para exportaciones a escala de data warehouse.
Errores comunes
1. Paginar sin ORDER BY
El orden de las filas en la base de datos no está garantizado.
2. Ordenar solo por una marca de tiempo no única
Las filas con marcas de tiempo iguales pueden moverse de un lado a otro de los límites de página.
3. Usar por defecto paginación por offset en conjuntos de datos enormes y mutables
Los offsets profundos y el movimiento de filas se vuelven problemáticos.
4. Suponer que la paginación por cursor crea una instantánea
No lo hace, salvo que se haya diseñado explícitamente así.
5. Dejar que los clientes elijan un tamaño de página ilimitado
Una sola solicitud puede convertirse en una exportación masiva.
6. Avanzar el cursor antes de que el procesamiento de la página sea duradero
Un fallo puede hacer que se salten registros.
7. Suponer que las páginas cortas significan el final de los datos
Usa metadatos de continuación explícitos.
8. Reutilizar un cursor con filtros u orden diferentes
Es posible que el cursor ya no represente el mismo conjunto de resultados.
9. Devolver totales exactos cuando son demasiado costosos
No hagas que cada solicitud de página pague un conteo completo a menos que el producto realmente lo necesite.
10. Usar la paginación para exportaciones masivas de datos
Usa un patrón de exportación asíncrona o de uso compartido de datos cuando la escala lo exija.
¿Te resultó útil este contenido?
¿Qué podríamos mejorar?
Gracias — esto me ayuda a mejorar Javi Builds.
Mantente al día
Recibe solo las novedades de Javi Builds que realmente te interesan.
Revisa tu bandeja de entrada
Te he enviado un enlace de confirmación. Tu suscripción se activará cuando la confirmes.