Cum proiectezi paginarea, filtrarea și sortarea pentru un endpoint de colecție?

Question

IT Interview Practice · Accepted Answer

Orice endpoint care returnează o colecție trebuie să **limiteze și modeleze** rezultatele. Trei preocupări — paginare, filtrare, sortare — stau toate în query string.

## Paginare: offset vs cursor

**Offset (bazat pe pagină)** — `?page=3&limit=20` sau `?offset=40&limit=20`.
```http
GET /orders?offset=40&limit=20 HTTP/1.1
```
Simplu și permite saltul la orice pagină, dar are două probleme la scară: `OFFSET 100000` forțează baza de date să scaneze și să arunce 100k de rânduri (lent), iar dacă rândurile sunt inserate/șterse între cereri, elementele **se deplasează** și vezi duplicate sau omisiuni.

**Cursor (keyset)** — clientul transmite un pointer opac către ultimul element văzut.
```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 }
}
```
Serverul traduce cursor-ul în `WHERE id > 1020 ORDER BY id LIMIT 20` — o căutare indexată care rămâne rapidă la orice adâncime și este **stabilă** față de inserări. Compromisul: fără acces aleatoriu la „pagina 500".

```text
Offset  → dataset-uri mici, UI-uri de admin, „sari la pagina N”
Cursor  → feed-uri mari/infinite, date în timp real, scroll pe mobil
```

## Filtrare și sortare

```http
GET /orders?status=shipped&min_total=100&sort=-created_at,id HTTP/1.1
```
- **Filtrează** cu parametri query field=value (`status=shipped`). Whitelist la câmpurile permise.
- **Sortează** cu un parametru `sort`; un prefix `-` înseamnă descrescător (`-created_at`). Suportă chei multiple pentru o ordonare stabilă.
- **Limitează întotdeauna `limit`** (ex. maxim 100), ca un client să nu poată cere un milion de rânduri.

## De ce contează

Aceasta este una dintre cele mai practice întrebări de design API pentru că aproape fiecare endpoint de listă o întâlnește, iar alegerea are consecințe reale de performanță. Intervievatorul sondează de obicei **compromisul offset-vs-cursor**: un candidat care recurge la paginare offset peste tot nu a simțit durerea lui `OFFSET 1000000` care scanează tabelul, sau bug-ul „rezultatelor deplasate" în care un utilizator care derulează un feed infinit vede aceeași postare de două ori pentru că a fost inserată una nouă. Cursor pagination le repară pe ambele transformând interogarea într-o căutare keyset indexată, de aceea fiecare API la scară mare (Twitter, Stripe, Slack) o folosește pentru feed-uri. Răspunsurile bune menționează și barierele operaționale — whitelisting la câmpurile de filtrare/sortare (pentru a evita interogări neindexate și injection) și limitarea `limit` (pentru a proteja baza de date) — ceea ce separă pe cineva care a rulat aceste endpoint-uri în producție de cineva care doar a citit despre ele.

Paginare: offset vs cursor

Filtrare și sortare

De ce contează

Întrebări conexe