Miten suunnittelet sivutuksen, suodatuksen ja lajittelun collection-endpointille?

Question

IT Interview Practice · Accepted Answer

Mikä tahansa endpoint, joka palauttaa collectionin, tarvitsee **rajoittaa ja muotoilla** tulokset. Kolme huolenaihetta — sivutus, suodatus, lajittelu — elävät kaikki query stringissä.

## Sivutus: offset vs. cursor

**Offset (sivupohjainen)** — `?page=3&limit=20` tai `?offset=40&limit=20`.
```http
GET /orders?offset=40&limit=20 HTTP/1.1
```
Yksinkertainen ja sallii hyppäämisen mille tahansa sivulle, mutta sillä on kaksi ongelmaa mittakaavassa: `OFFSET 100000` pakottaa tietokannan skannaamaan ja hylkäämään 100k riviä (hidas), ja jos rivejä lisätään/poistetaan pyyntöjen välillä, kohteet **siirtyvät** ja näet duplikaatteja tai ohituksia.

**Cursor (keyset)** — client välittää läpinäkymättömän osoittimen viimeksi nähtyyn kohteeseen.
```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 }
}
```
Palvelin kääntää cursorin muotoon `WHERE id > 1020 ORDER BY id LIMIT 20` — indeksoitu haku, joka pysyy nopeana millä tahansa syvyydellä ja on **vakaa** lisäyksiä vastaan. Kompromissi: ei satunnaispääsyä "sivulle 500".

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

## Suodatus ja lajittelu

```http
GET /orders?status=shipped&min_total=100&sort=-created_at,id HTTP/1.1
```
- **Suodata** field=value query paramilla (`status=shipped`). Whitelistaa sallitut kentät.
- **Lajittele** `sort`-paramilla; `-`-etuliite tarkoittaa laskevaa (`-created_at`). Tue moniavainta vakaan järjestyksen vuoksi.
- **Rajaa aina `limit`** (esim. max 100), jottei client voi pyytää miljoonaa riviä.

## Miksi se on tärkeää

Tämä on yksi käytännöllisimmistä API-suunnittelukysymyksistä, koska lähes jokainen listaendpoint törmää siihen, ja valinnalla on todellisia suorituskykyseurauksia. Haastattelija luotaa yleensä **offset-vs-cursor-kompromissia**: ehdokas, joka tarttuu offset-sivutukseen kaikkialla, ei ole tuntenut kipua `OFFSET 1000000` skannaamassa taulua, eikä "siirtyvien tulosten" bugia, jossa ääretöntä feediä vierittävä käyttäjä näkee saman postauksen kahdesti, koska uusi lisättiin. Cursor-sivutus korjaa molemmat muuttamalla kyselyn indeksoiduksi keyset-hauksi, minkä vuoksi jokainen suuren mittakaavan API (Twitter, Stripe, Slack) käyttää sitä feedeihin. Vahvat vastaukset mainitsevat myös operatiiviset kaiteet — suodatus/lajittelukenttien whitelistaus (indeksoimattomien kyselyjen ja injektion välttämiseksi) ja `limit`in rajaus (tietokannan suojaamiseksi) — mikä erottaa jonkun, joka on ajanut näitä endpointeja tuotannossa, jostakusta, joka on vain lukenut niistä.

Sivutus: offset vs. cursor

Suodatus ja lajittelu

Miksi se on tärkeää

Aiheeseen liittyvät kysymykset