¿Cómo se diseñan la paginación, el filtrado y la ordenación para un endpoint de collection?

Question

IT Interview Practice · Accepted Answer

Cualquier endpoint que devuelve una collection necesita **limitar y dar forma** a los resultados. Tres preocupaciones — paginación, filtrado, ordenación — viven todas en el query string.

## Paginación: offset vs cursor

**Offset (basada en páginas)** — `?page=3&limit=20` o `?offset=40&limit=20`.
```http
GET /orders?offset=40&limit=20 HTTP/1.1
```
Simple y permite saltar a cualquier página, pero tiene dos problemas a escala: `OFFSET 100000` obliga a la base de datos a escanear y descartar 100k filas (lento), y si se insertan/borran filas entre requests, los elementos **se desplazan** y ves duplicados o saltos.

**Cursor (keyset)** — el client pasa un puntero opaco al último elemento visto.
```http
GET /orders?limit=20&cursor=eyJpZCI6MTAyMH0 HTTP/1.1
```
```http
HTTP/1.1 200 OK

{
  "data": [ /* 20 orders */ ],
  "page": { "next_cursor": "eyJpZCI6MTA0MH0", "has_more": true }
}
```
El server traduce el cursor a `WHERE id > 1020 ORDER BY id LIMIT 20` — una búsqueda indexada que se mantiene rápida a cualquier profundidad y es **estable** ante inserciones. El compromiso: sin acceso aleatorio a la "página 500".

```text
Offset  → datasets pequeños, admin UIs, "saltar a la página N"
Cursor  → feeds grandes/infinitos, datos en tiempo real, scroll en móvil
```

## Filtrado y ordenación

```http
GET /orders?status=shipped&min_total=100&sort=-created_at,id HTTP/1.1
```
- **Filtra** con query params field=value (`status=shipped`). Pon en whitelist los fields permitidos.
- **Ordena** con un param `sort`; un prefijo `-` significa descendente (`-created_at`). Soporta multi-key para un orden estable.
- Siempre **limita `limit`** (p. ej. máximo 100) para que un client no pueda pedir un millón de filas.

## Por qué es importante

Esta es una de las preguntas de diseño de API más prácticas porque casi todo endpoint de lista se topa con ella, y la elección tiene consecuencias reales de rendimiento. El entrevistador suele explorar el **compromiso offset-vs-cursor**: un candidato que recurre a la paginación offset en todas partes no ha sentido el dolor de `OFFSET 1000000` escaneando la tabla, ni el bug de "resultados desplazados" donde un usuario que hace scroll en un feed infinito ve el mismo post dos veces porque se insertó uno nuevo. La paginación por cursor arregla ambos convirtiendo la query en una búsqueda keyset indexada, por lo que toda API a gran escala (Twitter, Stripe, Slack) la usa para los feeds. Las respuestas fuertes también mencionan las barandillas operativas — poner en whitelist los fields de filtrado/ordenación (para evitar queries sin índice e inyección) y limitar `limit` (para proteger la base de datos) — lo que separa a quien ha operado estos endpoints en producción de quien solo ha leído sobre ellos.

Paginación: offset vs cursor

Filtrado y ordenación

Por qué es importante

Preguntas relacionadas