Hoe ontwerp je paginering, filteren en sorteren voor een collectie-endpoint?

Question

IT Interview Practice · Accepted Answer

Elk endpoint dat een collectie retourneert moet de resultaten **beperken en vormgeven**. Drie zaken — paginering, filteren, sorteren — leven allemaal in de query string.

## Paginering: offset vs cursor

**Offset (pagina-gebaseerd)** — `?page=3&limit=20` of `?offset=40&limit=20`.
```http
GET /orders?offset=40&limit=20 HTTP/1.1
```
Eenvoudig en laat naar elke pagina springen, maar heeft twee problemen op schaal: `OFFSET 100000` dwingt de database 100k rijen te scannen en weg te gooien (traag), en als er rijen tussen requests worden toegevoegd/verwijderd, **verschuiven** items en zie je duplicaten of overslagen.

**Cursor (keyset)** — de client geeft een opaque pointer door naar het laatst geziene item.
```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 }
}
```
De server vertaalt de cursor naar `WHERE id > 1020 ORDER BY id LIMIT 20` — een geïndexeerde lookup die op elke diepte snel blijft en **stabiel** is tegen inserts. De afweging: geen willekeurige toegang tot "pagina 500".

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

## Filteren en sorteren

```http
GET /orders?status=shipped&min_total=100&sort=-created_at,id HTTP/1.1
```
- **Filter** met field=value query-params (`status=shipped`). Whitelist de toegestane velden.
- **Sorteer** met een `sort`-param; een `-`-prefix betekent aflopend (`-created_at`). Ondersteun meerdere sleutels voor een stabiele ordening.
- **Begrens `limit` altijd** (bv. max 100) zodat een client geen miljoen rijen kan opvragen.

## Waarom het belangrijk is

Dit is een van de meest praktische API-ontwerpvragen omdat bijna elk list-endpoint ermee te maken krijgt, en de keuze echte performancegevolgen heeft. De interviewer polst meestal de **offset-vs-cursor-afweging**: een kandidaat die overal offset-paginering pakt heeft de pijn niet gevoeld van `OFFSET 1000000` dat de tabel scant, of de "verschuivende resultaten"-bug waarbij een gebruiker die door een oneindige feed scrolt dezelfde post twee keer ziet omdat er een nieuwe is ingevoegd. Cursor-paginering lost beide op door de query in een geïndexeerde keyset-lookup te veranderen, en daarom gebruikt elke grootschalige API (Twitter, Stripe, Slack) het voor feeds. Sterke antwoorden noemen ook de operationele vangrails — filter/sort-velden whitelisten (om ongeïndexeerde queries en injectie te voorkomen) en `limit` begrenzen (om de database te beschermen) — wat iemand die deze endpoints in productie heeft gedraaid scheidt van iemand die er alleen over heeft gelezen.

Paginering: offset vs cursor

Filteren en sorteren

Waarom het belangrijk is

Gerelateerde vragen