Unabunije pagination, filtering, na sorting kwa endpoint ya collection?

Question

IT Interview Practice · Accepted Answer

Endpoint yoyote inayorudisha collection inahitaji **kupunguza na kuchagiza** matokeo. Mambo matatu — pagination, filtering, sorting — yote hukaa katika query string.

## Pagination: offset dhidi ya cursor

**Offset (yenye msingi wa ukurasa)** — `?page=3&limit=20` au `?offset=40&limit=20`.
```http
GET /orders?offset=40&limit=20 HTTP/1.1
```
Rahisi na huruhusu kuruka kwenye ukurasa wowote, lakini ina matatizo mawili kwa kiwango kikubwa: `OFFSET 100000` hulazimisha database ku-scan na kutupa rows 100k (polepole), na ikiwa rows zimeingizwa/zimefutwa kati ya requests, vitu **hu-shift** na unaona nakala au ku-skip.

**Cursor (keyset)** — client hupitisha pointer isiyo wazi kwa kitu cha mwisho kilichoonekana.
```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 hutafsiri cursor kuwa `WHERE id > 1020 ORDER BY id LIMIT 20` — lookup iliyo-indexed inayobaki haraka katika kina chochote na ni **thabiti** dhidi ya inserts. Trade-off: hakuna ufikiaji nasibu kwa "ukurasa 500".

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

## Filtering na sorting

```http
GET /orders?status=shipped&min_total=100&sort=-created_at,id HTTP/1.1
```
- **Filter** kwa query params za field=value (`status=shipped`). Weka whitelist ya fields zinazoruhusiwa.
- **Sort** kwa param ya `sort`; kiambishi `-` humaanisha kushuka (`-created_at`). Ruhusu multi-key kwa mpangilio thabiti.
- Daima **weka kikomo `limit`** (mfano max 100) ili client isiweze kuomba rows milioni.

## Kwa nini ni muhimu

Hili ni mojawapo ya maswali ya kivitendo zaidi ya usanifu wa API kwa sababu karibu kila list endpoint hukumbana nalo, na chaguo lina matokeo halisi ya utendaji. Mhoji kwa kawaida huchunguza **trade-off ya offset-dhidi-ya-cursor**: mgombea anayekimbilia offset pagination kila mahali hajahisi maumivu ya `OFFSET 1000000` iki-scan jedwali, au hitilafu ya "shifting results" ambapo mtumiaji anayesogeza feed isiyo na mwisho huona post ile ile mara mbili kwa sababu mpya iliingizwa. Cursor pagination hurekebisha vyote viwili kwa kugeuza query kuwa keyset lookup iliyo-indexed, ndiyo sababu kila API ya kiwango kikubwa (Twitter, Stripe, Slack) huitumia kwa feeds. Majibu imara pia hutaja lindalinda za kiuendeshaji — kuweka whitelist ya fields za filter/sort (kuepuka queries zisizo-indexed na injection) na kuweka kikomo `limit` (kulinda database) — jambo linalotenganisha mtu aliyeendesha endpoints hizi katika production na yule aliyezisoma tu.

Pagination: offset dhidi ya cursor

Filtering na sorting

Kwa nini ni muhimu

Maswali yanayohusiana