Come progetti paginazione, filtraggio e ordinamento per un endpoint di collection?

Question

IT Interview Practice · Accepted Answer

Qualsiasi endpoint che restituisce una collection deve **limitare e modellare** i risultati. Tre aspetti — paginazione, filtraggio, ordinamento — vivono tutti nella query string.

## Paginazione: offset vs cursor

**Offset (basata su pagina)** — `?page=3&limit=20` o `?offset=40&limit=20`.
```http
GET /orders?offset=40&limit=20 HTTP/1.1
```
Semplice e permette di saltare a qualsiasi pagina, ma ha due problemi su larga scala: `OFFSET 100000` costringe il database a scandire e scartare 100k righe (lento), e se le righe vengono inserite/eliminate tra le richieste, gli elementi **si spostano** e vedi duplicati o salti.

**Cursor (keyset)** — il client passa un puntatore opaco all'ultimo 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 }
}
```
Il server traduce il cursor in `WHERE id > 1020 ORDER BY id LIMIT 20` — una lookup indicizzata che resta veloce a qualsiasi profondità ed è **stabile** rispetto agli inserimenti. Il compromesso: nessun accesso casuale alla "pagina 500".

```text
Offset  → small datasets, admin UIs, "jump to page N"
Cursor  → large/infinite feeds, real-time data, mobile scroll
```

## Filtraggio e ordinamento

```http
GET /orders?status=shipped&min_total=100&sort=-created_at,id HTTP/1.1
```
- **Filtra** con query param field=value (`status=shipped`). Metti in whitelist i campi consentiti.
- **Ordina** con un param `sort`; un prefisso `-` significa discendente (`-created_at`). Supporta multi-chiave per un ordinamento stabile.
- **Limita sempre `limit`** (es. max 100) così che un client non possa richiedere un milione di righe.

## Perché è importante

Questa è una delle domande di design API più pratiche perché quasi ogni endpoint di lista la incontra, e la scelta ha conseguenze reali sulle performance. L'intervistatore di solito sonda il **compromesso offset-vs-cursor**: un candidato che ricorre ovunque alla paginazione offset non ha provato il dolore di `OFFSET 1000000` che scandisce la tabella, o il bug dei "risultati che si spostano" in cui un utente che scorre un feed infinito vede lo stesso post due volte perché ne è stato inserito uno nuovo. La paginazione cursor risolve entrambi trasformando la query in una lookup keyset indicizzata, ed è per questo che ogni API su larga scala (Twitter, Stripe, Slack) la usa per i feed. Le risposte forti menzionano anche i guardrail operativi — mettere in whitelist i campi di filtro/ordinamento (per evitare query non indicizzate e injection) e limitare `limit` (per proteggere il database) — il che separa chi ha gestito questi endpoint in produzione da chi ne ha solo letto.

Paginazione: offset vs cursor

Filtraggio e ordinamento

Perché è importante

Domande correlate