Una API que devuelve listas necesita limitar cuántos elementos entrega en cada respuesta. Sin paginación, una consulta puede consumir recursos innecesarios, aumentar la latencia y resultar difícil de manejar para quien integra el servicio. La decisión no se reduce a escoger una sintaxis: el mecanismo afecta a qué elementos ve cada consumidor cuando los datos cambian, cómo navega y qué garantías puede esperar.
Las dos opciones más comunes son la paginación por offset, que señala cuántos registros se omiten, y la paginación por cursor, que usa una referencia para continuar desde una posición. La elección depende del patrón de uso y de las garantías necesarias, no de que una estrategia sea universalmente mejor.
Qué debe garantizar una respuesta paginada
Antes de escoger el mecanismo, define el contrato de la colección. Como mínimo, decide el tamaño máximo de página, el orden de los elementos, cómo solicitar la página siguiente y qué sucede cuando ya no hay más resultados. También conviene especificar cómo se combinan paginación, filtros y ordenación.
El orden debe ser determinista. Ordenar solo por una fecha, por ejemplo, puede dejar varios registros empatados. Si el orden no define cómo resolver esos empates, distintos pedidos pueden devolver elementos en posiciones distintas. Añadir un criterio único, como el identificador del registro, permite establecer una secuencia inequívoca.
Una respuesta útil puede incluir los elementos y una referencia para continuar, además de metadatos como el tamaño efectivo de página. No todos los clientes necesitan conocer el total de resultados: calcularlo puede tener un coste y, en conjuntos que cambian con frecuencia, el total puede quedar desactualizado enseguida. Incluye solo la información necesaria para el caso de uso.
Paginación por offset: sencilla para saltar a una posición
Con offset, el cliente solicita un límite y cuántos elementos debe omitir. Una petición conceptual sería «devuelve 20 elementos a partir del registro 40». Es un modelo fácil de explicar y encaja con interfaces que ofrecen páginas numeradas, saltos a una página concreta o acceso directo a resultados más adelante en la lista.
Su principal ventaja es la simplicidad del contrato. Los clientes pueden construir enlaces a páginas y los equipos pueden razonar sobre rangos. También puede ser suficiente para colecciones pequeñas o relativamente estables, especialmente si la navegación directa es un requisito real.
El límite aparece cuando los datos cambian entre solicitudes. Supongamos que el cliente carga una primera página y, antes de pedir la siguiente, se inserta un elemento al principio del orden. El offset posterior puede volver a incluir un registro ya visto. Si se elimina un elemento antes de la posición solicitada, puede saltarse uno que aún no se había entregado. Offset no garantiza por sí solo una vista consistente de una colección dinámica.
Además, pedir posiciones muy profundas puede exigir recorrer o descartar muchos registros, según la base de datos, la consulta y los índices. No es una regla idéntica para todos los sistemas: hay que medir el comportamiento con consultas representativas. Si las páginas profundas se vuelven lentas, limita el salto máximo o evalúa otro mecanismo.
Paginación por cursor: continuar desde una posición
En la paginación por cursor, la respuesta proporciona una referencia que el cliente envía para obtener el siguiente tramo. El cursor representa una posición dentro de un orden; puede basarse, por ejemplo, en el valor de ordenación y un identificador que resuelva empates. El cliente no necesita conocer cómo está construida internamente esa referencia.
Para que funcione de forma predecible, la consulta debe mantener el mismo orden entre solicitudes. Un cursor basado en una fecha necesita un criterio adicional si varias filas comparten esa fecha. Los cambios concurrentes todavía pueden afectar a lo que aparece en páginas posteriores, pero una estrategia basada en la posición ordenada suele evitar los desplazamientos propios de saltar una cantidad de filas. No equivale necesariamente a una instantánea inmutable: esa garantía requiere diseñar y documentar un comportamiento adicional.
El cursor debería tratarse como opaco para el consumidor. Puede codificar datos de posición, pero codificar no significa cifrar ni proteger. No incluyas información sensible sin protección adecuada y valida que el cursor sea válido para la consulta, el usuario y el contexto de autorización correspondientes. Define también si expira y qué respuesta recibe el cliente cuando deja de ser utilizable.
Esta opción es adecuada para recorridos secuenciales, feeds, catálogos grandes y procesos que avanzan por resultados sin saltar a una página arbitraria. A cambio, complica la navegación directa y exige cuidar el formato, la validación y la compatibilidad de los cursores.
Criterios prácticos para elegir
Evalúa la experiencia que necesita el consumidor y las propiedades del conjunto de datos. La decisión puede resumirse así:
- Elige offset si son importantes las páginas numeradas o los saltos directos, el conjunto es acotado o los cambios durante la navegación tienen un impacto aceptable.
- Elige cursor si se recorren resultados de forma secuencial, el conjunto puede crecer mucho o las inserciones y eliminaciones hacen indeseables los desplazamientos entre páginas.
- Compara el coste real con consultas y tamaños representativos. La estrategia, los índices, los filtros y la base de datos influyen en el rendimiento.
- Considera el patrón de integración: una exportación por lotes puede necesitar avanzar de forma fiable; una interfaz de administración quizá valore saltar a una página concreta.
No mezcles ambos modelos sin explicar su alcance. Ofrecer offset para algunas consultas y cursor para otras puede tener sentido, pero cada colección debe documentar claramente su contrato. Tampoco presentes un cursor como garantía de consistencia total si el diseño solo conserva una posición y la colección sigue cambiando.
Filtros, ordenación y límites: el contrato completo
El cursor y la página siguiente deben corresponder a los mismos filtros y al mismo orden que originaron la primera respuesta. Si el cliente cambia esos parámetros, debe iniciar un recorrido nuevo, no reutilizar una referencia que representa otra consulta. La API puede rechazar esa combinación o emitir cursores que incluyan el contexto necesario para validarla.
Documenta un tamaño predeterminado y un máximo por petición. Un límite evita respuestas desmesuradas, pero debe ser coherente con el consumo esperado y no obligar al cliente a hacer un número excesivo de llamadas. Especifica qué ocurre con valores ausentes, inválidos o superiores al máximo: aplicar un límite o devolver un error son alternativas posibles; la clave es mantener un comportamiento consistente.
La ordenación solicitada por el usuario también requiere restricciones claras. Acepta solo campos y direcciones admitidos, establece un desempate determinista y evita que un cambio de ordenación se combine accidentalmente con un cursor anterior. Estos detalles reducen resultados repetidos, omisiones y consultas difíciles de optimizar.
Migrar sin romper consumidores existentes
Si una API ya expone offset, cambiar la respuesta o retirar parámetros puede romper aplicaciones e integraciones. Antes de migrar, identifica clientes, patrones de uso, páginas profundas y errores observados. Si no hay telemetría suficiente, instrumenta las solicitudes para conocer qué parámetros se usan, respetando las políticas de privacidad y retención aplicables.
- Define el nuevo contrato: orden, filtros, tamaño máximo, formato opaco del cursor y comportamiento ante cursores inválidos.
- Introduce compatibilidad de forma explícita: por ejemplo, una ruta o parámetro nuevo, o una transición documentada que conserve temporalmente el mecanismo anterior.
- Prueba cambios concurrentes, empates en el orden, última página, filtros modificados y cursores malformados o reutilizados fuera de contexto.
- Observa adopción y rendimiento antes de retirar la opción antigua. Comunica los cambios y ofrece instrucciones de actualización a los consumidores.
Evita que una respuesta cambie silenciosamente de significado según el cliente o que el servidor interprete un parámetro ambiguo de dos maneras. La compatibilidad debe ser comprobable y las fechas o condiciones de retirada deben estar documentadas, no supuestas.
Lista de comprobación para la decisión
- ¿Los consumidores necesitan saltar directamente a una página numerada?
- ¿Los datos cambian mientras se recorren y qué efecto tienen las repeticiones u omisiones?
- ¿El orden es determinista y tiene un criterio único para resolver empates?
- ¿Se han medido consultas profundas y tamaños de página realistas?
- ¿Están definidos filtros, límites, errores y reutilización de cursores?
- ¿Existe una estrategia de compatibilidad y una forma de observar la adopción?
Si la navegación directa es central y el conjunto es manejable, offset puede ser una elección razonable. Si predomina el recorrido secuencial y el volumen o los cambios hacen frágiles los desplazamientos, cursor suele encajar mejor. Documenta primero las garantías que necesitas y elige después el mecanismo: así la API responde a las necesidades reales de sus consumidores y puede evolucionar sin sorpresas.