¿Qué es la paginación de una API y por qué evita respuestas enormes?
Publicado el 2026-10-20 por frfrand
Paginación de APIs con limit/offset y cursores: cómo devolver listas grandes, manejar cambios de datos y evitar errores de rendimiento.
La paginación permite devolver una lista de datos por partes en lugar de enviar todos los registros de una sola vez. Es habitual en catálogos, historiales de pedidos y APIs con miles o millones de elementos.
Si una tienda tiene dos millones de productos, descargar toda la base de datos cada vez que alguien abre el catálogo no parece una gran idea.
La comparación con una biblioteca
Imaginá que preguntás por libros de programación. La bibliotecaria no vacía todos los estantes encima de la mesa. Te muestra una selección y te permite pasar a los siguientes resultados.
Una API paginada hace algo parecido: recibe información sobre cuánto devolver y desde qué punto continuar.
La paginación por limit y offset
Una API podría ofrecer:
GET /api/productos?limit=20&offset=40Eso solicita hasta veinte productos a partir de cierta posición. Es sencilla de implementar y permite construir páginas tradicionales: primera, segunda, tercera.
Pero tiene límites. Con muchas filas, algunas consultas con offset elevado pueden resultar costosas. Y si se agregan o eliminan productos entre solicitudes, el usuario podría ver registros repetidos o saltarse otros.
Por eso no hay que asumir que «página 4» identifica permanentemente el mismo conjunto de datos.
Paginación por cursor
Otra técnica utiliza un cursor que representa una posición lógica de continuación. La respuesta puede incluir una lista y un valor como next_cursor.
El cliente envía ese cursor para recuperar la siguiente tanda, sin depender necesariamente de contar desde el inicio cada vez.
Este enfoque puede funcionar mejor para listas que cambian con frecuencia, pero el cursor debe diseñarse con un orden estable y atributos apropiados. No es una clave mágica que resuelve cualquier problema de consistencia.
¿Qué debería devolver una buena API?
Además de los elementos, puede incluir un indicador de continuación y enlaces o parámetros para solicitar el siguiente conjunto. En ocasiones resulta útil informar el total de registros, pero calcularlo también puede tener costes.
Lo importante es documentar claramente las reglas: límite máximo de página, orden aplicado, filtros admitidos y comportamiento si el cursor caduca o es inválido.
El cliente no debería poder pedir arbitrariamente veinte millones de registros si esa operación puede afectar a todos los demás usuarios.
El orden es imprescindible
Imaginá consultar primero los veinte pedidos más nuevos. Si no definís explícitamente cómo ordenarlos, el motor de base de datos no promete devolverte siempre una secuencia lógica. La paginación sin orden estable puede producir resultados confusos.
Es útil ordenar por una fecha y resolver los empates con un identificador único. La estrategia exacta depende del motor y de cómo se insertan los registros.
¿Y cómo se compara con una búsqueda?
Buscar y paginar son problemas distintos. Una búsqueda decide qué registros coinciden con los filtros; la paginación decide cuántos se entregan y cómo continuar.
Si el usuario cambia los filtros, normalmente debería reiniciar el recorrido. Reutilizar el cursor anterior con otra consulta puede dar resultados incorrectos.
Tres errores que aparecen en producción
Permitir límites enormes: una única solicitud puede consumir demasiada memoria o tiempo de procesamiento.
Omitir el orden: las páginas dejan de tener un significado consistente.
Inventar un total exacto sin medir: en bases grandes, calcular el número exacto puede ser más caro que devolver la página solicitada.
Para APIs sensibles, también hay que verificar autorización: paginar no debe permitir obtener registros de otras personas.
¿Dónde entra ArduMaker?
Si publicás un backend en un VPS de ArduMaker, la paginación ayuda a reducir la carga de sus consultas y el volumen de datos transferidos. El panel puede facilitar el despliegue, pero el comportamiento de la API y su base de datos corresponde al proyecto.
En resumen: paginar no es dividir una pantalla visual en páginas. Es diseñar cómo recuperar grandes conjuntos de datos de forma eficiente, predecible y segura.
Fuentes: Guía de diseño de APIs de Microsoft · LIMIT y OFFSET en PostgreSQL.