Jak navrhnete stránkování, filtrování a řazení pro endpoint kolekce?

Question

IT Interview Practice · Accepted Answer

Každý endpoint, který vrací kolekci, musí výsledky **omezit a tvarovat**. Tři starosti — stránkování, filtrování, řazení — všechny žijí v query stringu.

## Stránkování: offset vs cursor

**Offset (podle stránek)** — `?page=3&limit=20` nebo `?offset=40&limit=20`.
```http
GET /orders?offset=40&limit=20 HTTP/1.1
```
Jednoduché a umožňuje skočit na libovolnou stránku, ale ve velkém má dva problémy: `OFFSET 100000` nutí databázi projít a zahodit 100k řádků (pomalé), a pokud se mezi požadavky vkládají/mažou řádky, položky se **posunou** a vidíte duplicity nebo přeskoky.

**Cursor (keyset)** — klient předává neprůhledný (opaque) ukazatel na poslední viděnou položku.
```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 }
}
```
Server přeloží cursor na `WHERE id > 1020 ORDER BY id LIMIT 20` — vyhledání přes index, které zůstává rychlé v jakékoli hloubce a je **stabilní** vůči vkládání. Kompromis: žádný náhodný přístup na „stránku 500“.

```text
Offset  → malé datasety, admin UI, "skok na stránku N"
Cursor  → velké/nekonečné feedy, real-time data, scroll na mobilu
```

## Filtrování a řazení

```http
GET /orders?status=shipped&min_total=100&sort=-created_at,id HTTP/1.1
```
- **Filtrujte** query parametry field=value (`status=shipped`). Povolená pole dejte na whitelist.
- **Řaďte** parametrem `sort`; prefix `-` znamená sestupně (`-created_at`). Podporujte více klíčů pro stabilní řazení.
- Vždy **omezte `limit`** (např. max 100), aby klient nemohl vyžádat milion řádků.

## Proč je to důležité

Tohle je jedna z nejpraktičtějších otázek návrhu API, protože na ni naráží téměř každý seznamový endpoint a volba má reálné výkonové důsledky. Tazatel obvykle zkoumá **kompromis offset-vs-cursor**: kandidát, který všude sahá po offset stránkování, nezažil bolest `OFFSET 1000000` skenujícího tabulku ani bug „posouvajících se výsledků“, kdy uživatel scrollující nekonečný feed vidí tentýž příspěvek dvakrát, protože byl vložen nový. Cursor stránkování řeší obojí tím, že mění dotaz na keyset lookup přes index, proto ho každé rozsáhlé API (Twitter, Stripe, Slack) používá pro feedy. Silné odpovědi zmiňují i provozní pojistky — whitelisting polí pro filtr/řazení (aby se předešlo neindexovaným dotazům a injection) a omezení `limit` (na ochranu databáze) — což odděluje někoho, kdo tyto endpointy provozoval v produkci, od někoho, kdo o nich jen četl.

Stránkování: offset vs cursor

Filtrování a řazení

Proč je to důležité

Související otázky