Kako dizajnirati straničenje, filtriranje i sortiranje za endpoint kolekcije?

Question

IT Interview Practice · Accepted Answer

Svaki endpoint koji vraća kolekciju treba **ograničiti i oblikovati** rezultate. Tri brige — straničenje, filtriranje, sortiranje — sve žive u query stringu.

## Straničenje: offset vs cursor

**Offset (temeljen na stranicama)** — `?page=3&limit=20` ili `?offset=40&limit=20`.
```http
GET /orders?offset=40&limit=20 HTTP/1.1
```
Jednostavan i dopušta skok na bilo koju stranicu, ali ima dva problema pri velikoj skali: `OFFSET 100000` prisiljava bazu da skenira i odbaci 100k redaka (sporo), a ako se reci umeću/brišu između zahtjeva, stavke se **pomiču** i vidite duplikate ili preskoke.

**Cursor (keyset)** — klijent prosljeđuje neprozirni (opaque) pokazivač na zadnju viđenu stavku.
```http
GET /orders?limit=20&cursor=eyJpZCI6MTAyMH0 HTTP/1.1
```
```http
HTTP/1.1 200 OK

{
  "data": [ /* 20 narudžbi */ ],
  "page": { "next_cursor": "eyJpZCI6MTA0MH0", "has_more": true }
}
```
Server prevodi cursor u `WHERE id > 1020 ORDER BY id LIMIT 20` — indeksirani lookup koji ostaje brz na bilo kojoj dubini i **stabilan** je na umetanja. Kompromis: nema nasumičnog pristupa "stranici 500".

```text
Offset  → mali skupovi podataka, admin sučelja, "skok na stranicu N"
Cursor  → veliki/beskonačni feedovi, real-time podaci, scroll na mobitelu
```

## Filtriranje i sortiranje

```http
GET /orders?status=shipped&min_total=100&sort=-created_at,id HTTP/1.1
```
- **Filtrirajte** query parametrima field=value (`status=shipped`). Whitelistajte dopuštena polja.
- **Sortirajte** `sort` parametrom; prefiks `-` znači silazno (`-created_at`). Podržite više ključeva za stabilan redoslijed.
- Uvijek **ograničite `limit`** (npr. max 100) kako klijent ne bi mogao zatražiti milijun redaka.

## Zašto je to važno

Ovo je jedno od najpraktičnijih pitanja o dizajnu API-ja jer ga pogađa gotovo svaki list endpoint, a izbor ima stvarne posljedice na performanse. Ispitivač obično istražuje **kompromis offset-vs-cursor**: kandidat koji posvuda poseže za offset straničenjem nije osjetio bol `OFFSET 1000000` skeniranja tablice, ni bug "pomicanja rezultata" gdje korisnik koji skrola beskonačni feed vidi isti post dvaput jer je novi umetnut. Cursor straničenje popravlja oboje pretvarajući upit u indeksirani keyset lookup, zbog čega ga svaki API velike skale (Twitter, Stripe, Slack) koristi za feedove. Snažni odgovori spominju i operativne zaštitne ograde — whitelistanje polja za filtriranje/sortiranje (radi izbjegavanja neindeksiranih upita i injectiona) i ograničavanje `limit`a (radi zaštite baze) — što razdvaja nekoga tko je pokretao te endpointe u produkciji od nekoga tko je samo čitao o njima.

Straničenje: offset vs cursor

Filtriranje i sortiranje

Zašto je to važno

Povezana pitanja