Paginación, filtros y ordenamiento en APIs

IRC-Mania Die Seite rund um Sicherheit und Programmierung

Internet, Sicherheit , Internet Relay Chat

Gesponsert

La paginación, los filtros y el ordenamiento permiten servir grandes volúmenes de datos de forma eficiente, consistente y amigable a través de una API.

Descripción compacta

La paginación limita la cantidad de registros que una API devuelve en una llamada. Previene respuestas grandes y lentas, y protege tanto el servidor como los clientes. Los filtros permiten restringir datos según criterios específicos sin necesidad de crear endpoints separados. El ordenamiento controla el orden de los resultados. Juntos, estos tres mecanismos forman la base para consultas de API flexibles. Los tipos más comunes de paginación son Offset Pagination, Cursor Pagination y Keyset Pagination. Cada uno tiene ventajas e inconvenientes en términos de simplicidad, consistencia y rendimiento. Los filtros y el ordenamiento generalmente se controlan mediante parámetros de query, donde las convenciones claras y los nombres descriptivos son fundamentales. Una buena API documenta sus opciones de paginación y filtrado de manera clara y proporciona en la respuesta metadatos útiles como enlaces, cantidad total o cursores.

Componentes principales

Offset Pagination

Offset Pagination utiliza parámetros como page y offset, junto con limit, para obtener una porción del conjunto de resultados. Ejemplo: ?page=2&limit=20. Este método es simple de implementar y comprender. Los inconvenientes incluyen degradación del rendimiento con valores grandes de offset e inconsistencias cuando el conjunto de resultados cambia entre páginas.

Cursor Pagination

Cursor Pagination utiliza un cursor opaco basado en un valor ordenado. Ejemplo: ?cursor=abc123&limit=20. Ofrece mejor rendimiento y consistencia que Offset Pagination con grandes volúmenes de datos. Los inconvenientes incluyen navegación más complicada hacia páginas arbitrarias y dependencia de un orden único bien definido.

Keyset Pagination

Keyset Pagination es similar a Cursor Pagination, pero utiliza valores explícitos como ?createdAfter=2026-07-01T00:00:00Z&limit=20. Tiene un rendimiento excelente y es muy estable, pero menos flexible cuando se usan múltiples campos de ordenamiento. Es ideal para flujos de datos ordenados por tiempo.

Page y Limit

page y limit son los parámetros clásicos de Offset Pagination. page indica la página, limit la cantidad de elementos por página. Los valores por defecto típicos son page=1 y limit=20. Las APIs deben hacer cumplir un limit máximo para prevenir abusos.

Total Count y Enlaces

Las respuestas deben contener metadatos que faciliten la navegación. Esto incluye total, page, limit, next, prev, first y last. Los enlaces HATEOAS ayudan a los clientes a navegar entre páginas sin necesidad de construir URLs manualmente.

Parámetros de filtro

Los filtros generalmente se controlan mediante parámetros de query. Ejemplos son ?status=active, ?category=books o ?minPrice=10&maxPrice=50. Los filtros deben tener nombres descriptivos, estar documentados y validados. Las combinaciones booleanas pueden expresarse mediante parámetros separados o una sintaxis de consulta de filtros.

Ordenamiento

El ordenamiento se controla frecuentemente mediante parámetros como sort u orderBy. Ejemplos son ?sort=name o ?sort=-createdAt, donde un signo menos indica orden descendente. Las convenciones claras y la documentación son importantes para que los clientes usen la API correctamente.

Parámetro de búsqueda

La búsqueda de texto completo se expresa generalmente mediante un parámetro como q o search, por ejemplo ?q=python. Las búsquedas más complejas pueden implementarse mediante servicios de búsqueda como Elasticsearch u OpenSearch y exponerse a través de una API de búsqueda dedicada.

Combinación de filtros, ordenamiento y paginación

En la práctica, los filtros, el ordenamiento y la paginación se combinan frecuentemente. Ejemplo: ?status=active&sort=-createdAt&page=1&limit=25. La API debe combinar estos parámetros de manera sensata, validarlos y documentarlos. Es importante mantener el orden de las operaciones de forma consistente.

Limit y valores por defecto

Un limit por defecto razonable reduce el volumen de datos y el tiempo de respuesta. Simultáneamente, debe aplicarse un limit máximo para prevenir solicitudes demasiado grandes. Los clientes deben poder elegir el limit dentro de los límites permitidos.

Consistencia con datos en crecimiento

Cuando el volumen de datos cambia durante la paginación, los registros pueden duplicarse o perderse. Cursor Pagination y Keyset Pagination son más estables en este aspecto que Offset Pagination. Con Offset Pagination, los clientes deben estar preparados para inconsistencias o la API debe usar snapshots.

Ejemplo práctico

Una API para productos soporta Offset Pagination, filtros y ordenamiento.

Solicitud:

GET /api/v1/products?category=electronics&minPrice=100&sort=-rating&page=2&limit=10

Respuesta:

{
  "data": [
    { "id": 15, "name": "Laptop", "price": 999, "rating": 4.8 },
    { "id": 22, "name": "Monitor", "price": 299, "rating": 4.7 }
  ],
  "pagination": {
    "page": 2,
    "limit": 10,
    "total": 145,
    "pages": 15,
    "next": "/api/v1/products?category=electronics&minPrice=100&sort=-rating&page=3&limit=10",
    "prev": "/api/v1/products?category=electronics&minPrice=100&sort=-rating&page=1&limit=10"
  }
}

El cliente puede navegar fácilmente mediante los enlaces sin necesidad de reconstruir los filtros y el ordenamiento.

IRC-Security.de

Cybersecurity Artikel und Tutorials

FAQ: Paginación, filtros y ordenamiento

Fuentes

1. https://www.rfc-editor.org/rfc/rfc8288
2. https://www.martinfowler.com/articles/patterns-of-distributed-systems/pagination.html
3. https://use-the-index-luke.com/no-offset

Lecturas recomendadas sobre API Design

Si quieres profundizar en API Design, consultas de datos y arquitectura de software, te sugerimos estos libros:

Premium VPS Hosting

Schnelle und sichere VPS Server

Gesponsert