Explorar guías rápidas · APIs

Tecnología: APIsCategoría: Diseño de APIsNivel: IntermedioActualizado

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
  1. Problema
  2. Respuesta rápida
  3. Código / comandos
  4. 1. Paginación solo con límite
  5. 2. Paginación por offset
  6. 3. Paginación por número de página
  7. 4. Devolver metadatos de paginación
  8. 5. Ten cuidado con los totales
  9. 6. Paginación por cursor
  10. 7. Hacer que los cursores sean opacos para los clientes
  11. 8. El contenido del cursor puede codificar el estado del orden
  12. 9. Paginación keyset
  13. 10. Usar un criterio de desempate determinista
  14. 11. Ajustar el predicado keyset a la dirección del orden
  15. 12. Paginación keyset compuesta
  16. 13. No expongas offsets de filas de la base de datos como cursor de negocio estable
  17. 14. La paginación por offset puede saltarse filas durante inserciones concurrentes
  18. 15. La paginación por offset puede duplicar filas durante eliminaciones
  19. 16. La paginación keyset suele ser más estable para el recorrido hacia delante
  20. 17. La paginación por cursor no crea automáticamente una instantánea
  21. 18. Añadir un límite superior estable para recorridos largos
  22. 19. Paginación por token de continuación
  23. 20. Los tokens de continuación pueden caducar
  24. 21. Vincular los cursores a la forma de la consulta original
  25. 22. Codificar la identidad de filtros y orden en los cursores opacos cuando sea útil
  26. 23. Firmar los cursores cuando los clientes no deban manipularlos
  27. 24. Cifrar los cursores solo cuando se necesite confidencialidad
  28. 25. Validar el tamaño de página
  29. 26. Limitar o rechazar solicitudes de páginas demasiado grandes
  30. 27. No cambiar el tamaño de página en silencio sin avisar al cliente
  31. 28. Conservar los filtros entre páginas
  32. 29. Conservar el orden entre páginas
  33. 30. Paginar después de filtrar, no antes
  34. 31. Paginar sobre una granularidad de negocio estable
  35. 32. Evitar paginar una consulta no determinista
  36. 33. No confiar nunca en el orden físico de las filas en la base de datos
  37. 34. Usar también un orden único para la paginación hacia atrás
  38. 35. Ejemplo de respuesta con cursor hacia delante
  39. 36. Ejemplo de pageInfo con soporte para recorrido hacia atrás
  40. 37. Paginación basada en enlaces
  41. 38. Paginación con el encabezado HTTP Link
  42. 39. Bucle de cliente para paginación por cursor
  43. 40. No detenerse basándose solo en la longitud de la página
  44. 41. Bucle de cliente con offset
  45. 42. Reintentar una página sin avanzar el estado
  46. 43. Hacer idempotente el procesamiento de páginas cuando sea posible
  47. 44. No suponer una entrega exactly-once a partir de la paginación
  48. 45. Guardar el checkpoint del token de continuación solo después de un procesamiento duradero
  49. 46. Almacenar los checkpoints de cursor junto con la identidad de la consulta
  50. 47. La caducidad de los cursores requiere una estrategia de reinicio
  51. 48. Usar watermarks para la sincronización incremental
  52. 49. Añadir un criterio de desempate a la sincronización por watermark
  53. 50. Usar con cuidado límites incrementales semiabiertos
  54. 51. Evitar updated_at > last_timestamp sin manejo de empates
  55. 52. La paginación por offset puede volverse más lenta con offsets profundos
  56. 53. La paginación keyset funciona mejor con índices adecuados
  57. 54. Evitar joins grandes después de paginar si cambian la multiplicidad de filas
  58. 55. Evitar paginar después de multiplicar filas
  59. 56. Devolver la última página vacía de forma coherente
  60. 57. Un cursor no válido debe ser un error del cliente
  61. 58. No exponer stack traces cuando falla la decodificación del cursor
  62. 59. Los límites de tasa se aplican a toda la paginación
  63. 60. Las cadenas de cursores secuenciales suelen ser secuenciales por naturaleza
  64. 61. Paralelizar por partición, no adivinando cursores
  65. 62. El tamaño de página afecta al rendimiento y al costo de los fallos
  66. 63. Comprimir las respuestas paginadas grandes
  67. 64. Limitar los campos cuando esté admitido
  68. 65. Evitar devolver colecciones anidadas enormes dentro de cada elemento paginado
  69. 66. La paginación y la ordenación deben ser compatibles
  70. 67. Rechazar los campos de ordenación no admitidos
  71. 68. Validar las entradas numéricas de paginación
  72. 69. Evitar el desbordamiento de enteros al calcular el offset
  73. 70. Usar un orden predeterminado estable
  74. 71. Tener en cuenta el comportamiento ante eliminaciones
  75. 72. Tener en cuenta las actualizaciones de las claves de ordenación
  76. 73. Preferir claves monótonas inmutables para feeds de tipo stream
  77. 74. Los UUID son únicos, pero no necesariamente útiles como claves de ordenación
  78. 75. La paginación no sustituye a la exportación masiva
  79. 76. Usar 202 para la creación de exportaciones asíncronas
  80. 77. Documentar la consistencia de las páginas
  81. 78. Documentar el ciclo de vida de los cursores
  82. 79. Monitorear el comportamiento de la paginación
  83. 80. Detectar usos patológicos del offset
  84. Qué significa el resultado
  85. Qué revisar
  86. Registros duplicados entre páginas
  87. Registros faltantes
  88. Las páginas profundas se vuelven más lentas
  89. El cursor deja de ser válido de repente
  90. El cliente entra en un bucle infinito
  91. El cliente se detiene antes de tiempo
  92. Notas de producción
  93. La semántica de paginación forma parte del contrato de la API
  94. El orden determinista es obligatorio
  95. Los valores de cursor deberían ser, en general, opacos
  96. La paginación no garantiza consistencia de instantánea
  97. Los reintentos y los checkpoints importan
  98. La extracción masiva puede requerir otra API
  99. Errores comunes
  100. 1. Paginar sin ORDER BY
  101. 2. Ordenar solo por una marca de tiempo no única
  102. 3. Usar por defecto paginación por offset en conjuntos de datos enormes y mutables
  103. 4. Suponer que la paginación por cursor crea una instantánea
  104. 5. Dejar que los clientes elijan un tamaño de página ilimitado
  105. 6. Avanzar el cursor antes de que el procesamiento de la página sea duradero
  106. 7. Suponer que las páginas cortas significan el final de los datos
  107. 8. Reutilizar un cursor con filtros u orden diferentes
  108. 9. Devolver totales exactos cuando son demasiado costosos
  109. 10. Usar la paginación para exportaciones masivas de datos
  110. Siguiente paso
  111. 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.


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:

  • 429
  • Retry-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.

Siguiente paso

Usa la forma de los datos y la necesidad del cliente para elegir el patrón.

  • Conjunto de datos pequeño y estable con navegación directa entre páginas → la paginación por página/offset puede ser suficiente.
  • Conjunto de datos grande recorrido secuencialmente → usa paginación por cursor/keyset.
  • El conjunto de datos cambia con frecuencia mientras los clientes lo recorren → usa una semántica keyset/cursor determinista y documenta la consistencia.
  • Las marcas de tiempo son la clave del cursor → añade un criterio de desempate único.
  • El cliente necesita un reinicio fiable → guarda el checkpoint solo después de un procesamiento duradero.
  • El cursor caduca → define el comportamiento de reinicio/watermark.
  • Los offsets profundos son lentos → inspecciona el plan de consulta y avanza hacia la paginación keyset.
  • El cliente necesita todos los datos a escala de data warehouse → diseña una exportación asíncrona en lugar de millones de solicitudes de páginas.
  • Los resultados de la paginación aparecen duplicados o faltan → revisa el orden, los cambios en los datos, los predicados de continuación y la lógica de checkpoint.
  • La propia solicitud a la API está fallando → pasa a Diagnosticar solicitudes de API.

← Todas las guías rápidas