Blog

Paginación de API REST: Guía Detallada

Rebecca Kovács

Rebecca Kovács

7 June 2025

Paginación de API REST: Guía Detallada

En el mundo del desarrollo de aplicaciones modernas, las API REST sirven como la capa de comunicación fundamental, permitiendo que sistemas dispares intercambien datos sin problemas. A medida que las aplicaciones crecen en escala y complejidad, también lo hace el volumen de datos que manejan. Solicitar un conjunto de datos completo, que potencialmente contenga millones o incluso miles de millones de registros, en una sola llamada a la API es ineficiente, poco fiable y un importante cuello de botella en el rendimiento. Aquí es donde entra en juego una técnica crucial en el diseño y desarrollo de API: la paginación de API REST. Esta guía proporciona una visión profunda y completa de la implementación de la paginación en API REST, cubriendo desde conceptos fundamentales hasta implementaciones avanzadas en el mundo real utilizando varias pilas tecnológicas como Node.js, Python y .NET.

💡
¿Quieres una excelente herramienta de prueba de API que genere hermosa Documentación de API?

¿Quieres una plataforma integrada, todo en uno, para que tu Equipo de Desarrolladores trabaje con máxima productividad?

Apidog satisface todas tus demandas, y reemplaza a Postman a un precio mucho más asequible!
botón

Los Fundamentos de la Paginación de API REST

Antes de sumergirnos en ejemplos de código complejos y patrones de diseño, es esencial tener una comprensión sólida de qué es la paginación y por qué es un aspecto no negociable del diseño profesional de API.

¿Qué es la Paginación en API REST?

En esencia, la paginación de API REST es una técnica utilizada para tomar la respuesta de un endpoint de API REST y segmentarla en unidades más pequeñas y manejables, a menudo llamadas "páginas". En lugar de entregar un conjunto de datos potencialmente masivo de una sola vez, la API devuelve un fragmento pequeño y predecible de los datos. Crucialmente, la respuesta de la API también incluye metadatos que permiten a un cliente obtener incrementalmente fragmentos subsiguientes si necesita más datos.

Este proceso es análogo a las páginas de un libro o a los resultados de búsqueda en Google. Se le presenta la primera página de resultados, junto con controles para navegar a la segunda, tercera, y así sucesivamente. Como señalan comunidades de desarrolladores como DEV Community y plataformas como Merge.dev, este es el proceso de dividir un gran conjunto de datos en fragmentos más pequeños, que pueden ser obtenidos incrementalmente por un cliente si realmente desea todos esos datos. Es un concepto fundamental para construir aplicaciones robustas y escalables.

¿Por qué la Paginación es un Requisito Fundamental en el Diseño Moderno de API?

La motivación principal para la paginación es asegurar que las respuestas de la API sean más fáciles de manejar tanto para el servidor como para el cliente. Sin ella, las aplicaciones enfrentarían limitaciones severas y una mala experiencia de usuario. Los beneficios clave incluyen:

Estrategias y Técnicas Comunes de Paginación

Hay varias formas de implementar la paginación, pero dos estrategias principales se han convertido en los estándares de facto en la industria. La elección entre ellas tiene implicaciones significativas para el rendimiento, la consistencia de los datos y la experiencia del usuario.

Paginación Basada en Offset: El Enfoque Fundamental

La paginación basada en offset, a menudo llamada "paginación por número de página", es frecuentemente el primer enfoque que aprenden los desarrolladores. Es conceptualmente simple y se ve en muchas aplicaciones web. Funciona utilizando dos parámetros principales:

Una solicitud típica se ve así: GET /api/products?limit=25&offset=50

Esto se traduciría en una consulta SQL como:SQL

SELECT * FROM products ORDER BY created_at DESC LIMIT 25 OFFSET 50;

Esta consulta omite los primeros 50 productos y recupera los siguientes 25 (es decir, productos 51-75).

Pros:

Contras y Limitaciones:

Paginación Basada en Cursor (Keyset): La Solución Escalable

La paginación basada en cursor, también conocida como paginación keyset o seek, resuelve los problemas de rendimiento y consistencia del método offset. En lugar de un número de página, utiliza un "cursor", que es un puntero estable y opaco a un registro específico en el conjunto de datos.

El flujo es el siguiente:

  1. El cliente realiza una solicitud inicial para una página de datos.
  2. El servidor devuelve la página de datos, junto con un cursor que apunta al último elemento de ese conjunto.
  3. Para la siguiente página, el cliente envía ese cursor de vuelta al servidor.
  4. El servidor luego recupera los registros que vienen después de ese cursor específico, efectivamente "buscando" (seeking) a ese punto en el conjunto de datos.

El cursor es típicamente un valor codificado derivado de la(s) columna(s) por la(s) que se ordena. Por ejemplo, si se ordena por created_at (una marca de tiempo), el cursor podría ser la marca de tiempo del último registro. Para manejar empates, a menudo se incluye una segunda columna única (como el id del registro).

Una solicitud que utiliza un cursor se ve así: GET /api/products?limit=25&after_cursor=eyJjcmVhdGVkX2F0IjoiMjAyNS0wNi0wN1QxODowMDowMC4wMDBaIiwiaWQiOjg0N30=

Esto se traduciría en una consulta SQL mucho más eficiente:SQL

SELECT * FROM products
WHERE (created_at, id) < ('2025-06-07T18:00:00.000Z', 847)
ORDER BY created_at DESC, id DESC
LIMIT 25;

Esta consulta utiliza un índice en (created_at, id) para "buscar" (seek) instantáneamente el punto de inicio correcto, evitando un escaneo completo de la tabla y haciéndola consistentemente rápida independientemente de cuán profunda sea la paginación del usuario.

Pros:

Contras:

Una Comparación de los Dos Tipos Principales de Paginación

La elección entre la paginación offset y la basada en cursor depende completamente del caso de uso.

CaracterísticaPaginación OffsetPaginación Basada en Cursor
RendimientoPobre para páginas profundas en conjuntos de datos grandes.Excelente y constante a cualquier profundidad.
Consistencia de DatosPropensa a perder/repetir datos (desplazamiento de página).Alta; los nuevos datos no afectan la paginación.
NavegaciónPuede saltar a cualquier página.Limitado a páginas siguientes/anteriores.
ImplementaciónSimple y directa.Más compleja; requiere lógica de cursor.
Caso de Uso IdealConjuntos de datos pequeños y estáticos; interfaces de administración.Feeds de desplazamiento infinito; conjuntos de datos grandes y dinámicos.

Mejores Prácticas de Implementación para la Paginación del Lado del Servidor

Independientemente de la estrategia elegida, adherirse a un conjunto de mejores prácticas resultará en una API limpia, predecible y fácil de usar. Esto es a menudo una parte clave para responder a "¿Cuál es la mejor práctica de paginación del lado del servidor?".

Diseñando la Carga de Respuesta de Paginación

Un error común es devolver simplemente un array de resultados. Una carga de respuesta de paginación bien diseñada debe ser un objeto que "envuelva" los datos e incluya metadatos de paginación claros.JSON

{
  "data": [
    { "id": 101, "name": "Product A" },
    { "id": 102, "name": "Product B" }
  ],
  "pagination": {
    "next_cursor": "eJjcmVhdGVkX2F0Ij...",
    "has_next_page": true
  }
}

Para la paginación offset, los metadatos se verían diferentes:JSON

{
  "data": [
    // ... results
  ],
  "metadata": {
    "total_results": 8452,
    "total_pages": 339,
    "current_page": 3,
    "per_page": 25
  }
}

Esta estructura hace que sea trivial para el cliente saber si hay más datos para obtener o para renderizar controles de interfaz de usuario.

Uso de Enlaces de Hipermedia para la Navegación (HATEOAS)

Un principio fundamental de REST es HATEOAS (Hypermedia as the Engine of Application State). Esto significa que la API debe proporcionar a los clientes enlaces para navegar a otros recursos o acciones. Para la paginación, esto es increíblemente potente. Como se demuestra en la Documentación de GitHub, una forma estandarizada de hacerlo es con el encabezado HTTP Link.

Link: <https://api.example.com/items?page=3>; rel="next", <https://api.example.com/items?page=1>; rel="prev"

Alternativamente, estos enlaces pueden colocarse directamente en el cuerpo de la respuesta JSON, lo que a menudo es más fácil de consumir para los clientes JavaScript:JSON

"pagination": {
  "links": {
    "next": "https://api.example.com/items?limit=25&offset=75",
    "previous": "https://api.example.com/items?limit=25&offset=25"
  }
}

Esto libera al cliente de tener que construir URLs manualmente.

Permitir a los Clientes Controlar el Tamaño de Página

Es una buena práctica permitir a los clientes solicitar páginas adicionales de resultados para respuestas paginadas y también cambiar el número de resultados devueltos en cada página. Esto se hace típicamente con un parámetro de consulta limit o per_page. Sin embargo, el servidor siempre debe imponer un límite máximo razonable (por ejemplo, 100) para evitar que los clientes soliciten demasiados datos a la vez y sobrecarguen el sistema.

Combinando Paginación con Filtrado y Ordenación

Las API del mundo real rara vez solo pagan; también necesitan soportar filtrado y ordenación. Como se muestra en tutoriales que cubren tecnologías como .NET, añadir estas características es un requisito común.

Una solicitud compleja podría verse así: GET /api/products?status=published&sort=-created_at&limit=50&page=2

Al implementar esto, es crucial que los parámetros de filtrado y ordenación se consideren parte de la lógica de paginación. El orden de sort debe ser estable y determinista para que la paginación funcione correctamente. Si el orden de clasificación no es único, debe añadir una columna desempate única (como id) para asegurar un ordenamiento consistente entre páginas.

Ejemplos de Implementación en el Mundo Real

Exploremos cómo implementar estos conceptos en varios frameworks populares.

Paginación de API REST en Python con Django REST Framework

Una de las combinaciones más populares para construir API es Python con el Django REST Framework (DRF). DRF proporciona un soporte potente e integrado para la paginación, lo que facilita enormemente el inicio. Ofrece clases para diferentes estrategias:

Puede configurar un estilo de paginación predeterminado globalmente y luego simplemente usar un ListAPIView genérico, y DRF se encarga del resto. Este es un excelente ejemplo de paginación de api rest en python.Python

# In your settings.py
REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.CursorPagination',
    'PAGE_SIZE': 50
}

# In your views.py
class ProductListView(generics.ListAPIView):
    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    # DRF handles the entire pagination logic automatically!

Construyendo una API REST Paginada con Node.js, Express y TypeScript

En el ecosistema de Node.js, a menudo se construye la lógica de paginación manualmente, lo que le da control total. Esta sección de la guía proporciona una visión conceptual de la construcción de paginación con Node.js, Express y TypeScript.

Aquí hay un ejemplo simplificado de implementación de paginación basada en cursor:TypeScript

// In your Express controller
app.get('/products', async (req: Request, res: Response) => {
  const limit = parseInt(req.query.limit as string) || 25;
  const cursor = req.query.cursor as string;

  let query = db.selectFrom('products').orderBy('createdAt', 'desc').orderBy('id', 'desc').limit(limit);

  if (cursor) {
    const { createdAt, id } = JSON.parse(Buffer.from(cursor, 'base64').toString('ascii'));
    // Add the WHERE clause for the cursor
    query = query.where('createdAt', '<=', createdAt).where('id', '<', id);
  }

  const products = await query.execute();

  const nextCursor = products.length > 0
    ? Buffer.from(JSON.stringify({
        createdAt: products[products.length - 1].createdAt,
        id: products[products.length - 1].id
      })).toString('base64')
    : null;

  res.json({
    data: products,
    pagination: { next_cursor: nextCursor }
  });
});

Paginación en un Ecosistema Java o .NET

Los frameworks en otros ecosistemas también proporcionan un soporte robusto para la paginación.

### Un Caso de Uso del Mundo Real: Paginando una API de Catálogo de Productos

Considere un sitio web de comercio electrónico con una "API de Catálogo de Productos". Este es un perfecto caso de uso del mundo real. El catálogo es grande y dinámico, con nuevos productos que se añaden con frecuencia.

Temas Avanzados y Problemas Comunes

Como a menudo descubren los desarrolladores en Stack Overflow y Reddit, construir un sistema de paginación verdaderamente robusto requiere manejar muchos detalles y casos extremos.

Cómo Asegurar la Consistencia de los Datos en una API Paginada

Este es uno de los temas avanzados más críticos. Como se discutió, la única forma fiable de garantizar la consistencia de los datos en un sistema con escrituras frecuentes es usar paginación keyset/cursor. Su diseño inherentemente previene el desplazamiento de página. Si por alguna razón está atascado con la paginación offset, existen algunas soluciones complejas, como crear una instantánea temporal e inmutable de los IDs para el conjunto completo de resultados y paginar a través de esa lista, pero esto es altamente con estado y generalmente no se recomienda para API REST.

Manejo de Casos Extremos Extraños

Una API lista para producción debe manejar con gracia las entradas incorrectas. Considere estos casos extremos comunes:

Implementación del Lado del Cliente

El lado del cliente es donde se consume la lógica de paginación. Usar JavaScript para obtener datos paginados de una API REST como un profesional implica leer los metadatos de paginación y usarlos para realizar solicitudes subsiguientes.

Aquí hay un ejemplo simple de fetch para un botón "Cargar Más" utilizando paginación basada en cursor:JavaScript

const loadMoreButton = document.getElementById('load-more');
let nextCursor = null; // Store the cursor globally or in component state

async function fetchProducts(cursor) {
  const url = cursor ? `/api/products?cursor=${cursor}` : '/api/products';
  const response = await fetch(url);
  const data = await response.json();

  // ... render the new products ...
  nextCursor = data.pagination.next_cursor;

  if (!nextCursor) {
    loadMoreButton.disabled = true; // No more pages
  }
}

loadMoreButton.addEventListener('click', () => fetchProducts(nextCursor));

// Initial load
fetchProducts(null);

El Futuro de la Recuperación de Datos de API y los Estándares de Paginación

Aunque REST ha sido dominante durante años, el panorama siempre está evolucionando.

Estándares de Paginación de API REST en Evolución

No existe un único RFC formal que defina los estándares de paginación de API REST. Sin embargo, ha surgido un conjunto de convenciones sólidas, impulsadas por las API públicas de importantes empresas tecnológicas como GitHub, Stripe y Atlassian. Estas convenciones, como el uso del encabezado Link y la provisión de metadatos claros, se han convertido en el estándar de facto. La consistencia es clave; una plataforma de API bien diseñada utilizará la misma estrategia de paginación en todos sus endpoints basados en listas.

El Impacto de GraphQL en la Paginación

GraphQL presenta un paradigma diferente. En lugar de múltiples endpoints, tiene un único endpoint donde los clientes envían consultas complejas especificando los datos exactos que necesitan. Sin embargo, la necesidad de paginar grandes listas de datos no desaparece. La comunidad GraphQL también ha estandarizado la paginación

Practica el diseño de API en Apidog

Descubre una forma más fácil de construir y usar APIs

Registrarse gratisDescargar