Definition
Imagina que cada vez que buscas en Google, intentara cargar los 10 mil millones de resultados coincidentes de una vez. Tu navegador colapsaría, y esperarías eternamente sin obtener nada útil. La paginación resuelve este problema dividiendo grandes conjuntos de resultados en fragmentos más pequeños y digeribles - como servir una comida en platos en lugar de volcar todo en la mesa de una vez.
Cuando una API tiene miles o millones de registros, enviarlos todos en una sola respuesta sería lento, desperdiciaría ancho de banda y abrumaría a la aplicación cliente. En cambio, la paginación te permite solicitar datos en páginas: “dame los items 1-20” luego “dame los items 21-40” y así sucesivamente. El servidor hace menos trabajo por petición, la red transporta cargas más pequeñas, y tu aplicación puede mostrar resultados inmediatamente mientras los usuarios se desplazan para ver más.
Hay varios sabores de paginación, cada uno con sus compromisos. La paginación basada en offset usa números de página (page=2, limit=20) - simple pero puede perder o duplicar items si los datos cambian entre peticiones. La paginación basada en cursor usa un puntero al último item que viste - más confiable pero no puedes saltar a una página específica. La elección correcta depende de tus datos y cómo los usuarios interactúan con ellos. Los feeds de redes sociales típicamente usan cursores (scroll infinito), mientras que los resultados de búsqueda a menudo usan offsets (números de página).
Example
La paginación está en todas partes, moldeando cómo consumes información en línea:
Feeds de Redes Sociales: Cuando te desplazas por Instagram o Twitter/X, estás experimentando paginación basada en cursor. La app carga 20-30 publicaciones, luego cuando te acercas al final, obtiene el siguiente lote usando el ID de la última publicación como cursor. Nunca ves números de página porque el feed está cambiando constantemente - la paginación por cursor maneja esto elegantemente.
Resultados de Búsqueda en E-commerce: Cuando buscas “zapatillas deportivas” en Amazon y ves “Página 1 de 47”, eso es paginación basada en offset. Puedes hacer clic para saltar directamente a la página 10. Amazon te muestra exactamente 48 items por página, y los enlaces de navegación te permiten navegar sistemáticamente a través de miles de productos.
Bandeja de Entrada de Email: Gmail usa paginación para mostrar tu bandeja de entrada en fragmentos manejables. Los botones “Anterior” y “Siguiente” se mueven a través de tus emails, y puedes configurar cuántos mensajes aparecen por página. Sin paginación, cargar una bandeja de entrada de años con 50,000 emails sería imposible.
Paneles de Administración de Base de Datos: Herramientas como phpMyAdmin o Sequel Pro paginan las tablas de base de datos. Al ver una tabla con millones de filas, muestran 30 filas a la vez con controles para navegar. Esto previene cargar accidentalmente tantos datos que la herramienta se congele.
Ejemplos de Documentación de API: La documentación de la API de Stripe muestra respuestas paginadas con has_more: true y un parámetro starting_after. Esto enseña a los desarrolladores el patrón: solicitar una página, verificar si hay más, usar el cursor para obtener el siguiente lote.
Analogía
El Fichero de la Biblioteca (Digitalizado): ¿Recuerdas los ficheros de biblioteca? Al buscar libros sobre “historia”, no obtendrías todas las fichas de una vez - hojearías un cajón, una sección a la vez. La paginación funciona igual: ves un lote manejable, y los controles te permiten avanzar, retroceder, o saltar a una sección específica.
El Carrusel de Netflix: Cuando navegas por Netflix, ves una fila de quizás 6-8 miniaturas de películas con flechas para desplazarte izquierda y derecha. Detrás de escena, Netflix no carga todas las películas en esa categoría - carga unas pocas a la vez mientras te desplazas. Eso es paginación proporcionando una experiencia fluida mientras conserva ancho de banda.
El Menú del Restaurante con Platos: Un menú degustación en un restaurante elegante no trae los 12 platos de una vez. Recibes un plato, lo disfrutas, luego llega el siguiente cuando estás listo. La paginación sirve datos de la misma manera - en platos que tu aplicación puede manejar y los usuarios pueden digerir.
La Suscripción a Revista: No recibes toda tu suscripción anual de 12 revistas en un paquete masivo. Llegan mensualmente - un número a la vez. Cada revista es como una “página” de tu suscripción, entregada cuando estás listo para el siguiente lote de contenido.
Code Example
// Offset-based pagination
GET /api/products?page=2&limit=20
{
"data": [...],
"pagination": {
"page": 2,
"limit": 20,
"total": 157,
"totalPages": 8
},
"links": {
"first": "/api/products?page=1&limit=20",
"next": "/api/products?page=3&limit=20",
"last": "/api/products?page=8&limit=20"
}
}