Comment concevoir la pagination, le filtrage et le tri pour un endpoint de collection ?

Question

IT Interview Practice · Accepted Answer

Tout endpoint qui retourne une collection doit **limiter et façonner** les résultats. Trois préoccupations — pagination, filtrage, tri — vivent toutes dans la query string.

## Pagination : offset vs cursor

**Offset (basé sur les pages)** — `?page=3&limit=20` ou `?offset=40&limit=20`.
```http
GET /orders?offset=40&limit=20 HTTP/1.1
```
Simple et permet de sauter à n'importe quelle page, mais présente deux problèmes à l'échelle : `OFFSET 100000` force la base de données à scanner et jeter 100k lignes (lent), et si des lignes sont insérées/supprimées entre les requêtes, les éléments **se décalent** et vous voyez des doublons ou des sauts.

**Cursor (keyset)** — le client passe un pointeur opaque vers le dernier élément vu.
```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 }
}
```
Le serveur traduit le cursor en `WHERE id > 1020 ORDER BY id LIMIT 20` — une recherche indexée qui reste rapide à n'importe quelle profondeur et **stable** face aux insertions. Le compromis : pas d'accès aléatoire à la « page 500 ».

```text
Offset  → petits datasets, admin UIs, « sauter à la page N »
Cursor  → feeds larges/infinis, données temps réel, scroll mobile
```

## Filtrage et tri

```http
GET /orders?status=shipped&min_total=100&sort=-created_at,id HTTP/1.1
```
- **Filtrer** avec des query params field=value (`status=shipped`). Whitelistez les champs autorisés.
- **Trier** avec un param `sort` ; un préfixe `-` signifie décroissant (`-created_at`). Supportez plusieurs clés pour un ordre stable.
- **Plafonnez toujours `limit`** (p. ex. max 100) pour qu'un client ne puisse pas demander un million de lignes.

## Pourquoi c'est important

C'est l'une des questions de conception d'API les plus pratiques car presque chaque endpoint de liste la rencontre, et le choix a de réelles conséquences de performance. Le recruteur sonde généralement le **compromis offset-vs-cursor** : un candidat qui dégaine la pagination offset partout n'a pas ressenti la douleur de `OFFSET 1000000` scannant la table, ni le bug des « résultats qui se décalent » où un utilisateur scrollant un feed infini voit deux fois le même post parce qu'un nouveau a été inséré. La pagination cursor corrige les deux en transformant la requête en une recherche keyset indexée, c'est pourquoi toute API à grande échelle (Twitter, Stripe, Slack) l'utilise pour les feeds. Les bonnes réponses mentionnent aussi les garde-fous opérationnels — whitelister les champs de filtre/tri (pour éviter les requêtes non indexées et l'injection) et plafonner `limit` (pour protéger la base de données) — ce qui distingue quelqu'un qui a exploité ces endpoints en production de quelqu'un qui n'a fait qu'en lire la théorie.

Pagination : offset vs cursor

Filtrage et tri

Pourquoi c'est important

Questions connexes