Como você projeta paginação, filtro e ordenação para um endpoint de collection?

Question

IT Interview Practice · Accepted Answer

Qualquer endpoint que retorna uma collection precisa **limitar e moldar** os resultados. Três preocupações — paginação, filtro, ordenação — todas ficam na query string.

## Paginação: offset vs cursor

**Offset (baseado em página)** — `?page=3&limit=20` ou `?offset=40&limit=20`.
```http
GET /orders?offset=40&limit=20 HTTP/1.1
```
Simples e permite pular para qualquer página, mas tem dois problemas em escala: `OFFSET 100000` força o banco de dados a varrer e descartar 100k linhas (lento), e se linhas são inseridas/deletadas entre requests, os itens **se deslocam** e você vê duplicatas ou pulos.

**Cursor (keyset)** — o client passa um ponteiro opaco para o último item 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 }
}
```
O server traduz o cursor em `WHERE id > 1020 ORDER BY id LIMIT 20` — uma busca indexada que permanece rápida em qualquer profundidade e é **estável** contra inserções. O trade-off: sem acesso aleatório à "página 500".

```text
Offset  → datasets pequenos, admin UIs, "pular para a página N"
Cursor  → feeds grandes/infinitos, dados em tempo real, scroll no mobile
```

## Filtro e ordenação

```http
GET /orders?status=shipped&min_total=100&sort=-created_at,id HTTP/1.1
```
- **Filtre** com query params field=value (`status=shipped`). Faça whitelist dos campos permitidos.
- **Ordene** com um param `sort`; um prefixo `-` significa decrescente (`-created_at`). Suporte múltiplas chaves para uma ordenação estável.
- Sempre **limite o `limit`** (ex. máx. 100) para um client não conseguir pedir um milhão de linhas.

## Por que isso importa

Esta é uma das perguntas de design de API mais práticas porque quase todo endpoint de lista esbarra nela, e a escolha tem consequências reais de desempenho. O entrevistador geralmente está sondando o **trade-off offset-vs-cursor**: um candidato que recorre à paginação por offset em todo lugar não sentiu a dor de `OFFSET 1000000` varrendo a tabela, ou o bug de "resultados que se deslocam" onde um usuário rolando um feed infinito vê o mesmo post duas vezes porque um novo foi inserido. A paginação por cursor conserta ambos transformando a query em uma busca keyset indexada, e é por isso que toda API de grande escala (Twitter, Stripe, Slack) a usa para feeds. Respostas fortes também mencionam as proteções operacionais — whitelist dos campos de filtro/ordenação (para evitar queries sem índice e injection) e limitar o `limit` (para proteger o banco de dados) — o que separa quem já operou esses endpoints em produção de quem apenas leu sobre eles.

Paginação: offset vs cursor

Filtro e ordenação

Por que isso importa

Perguntas relacionadas