API-uri REST
Resurse și metode, status-uri corecte, erori consecvente, paginare offset vs cursor.
Actualizat
Ce este un API REST
Un API e interfața prin care un program cere date altui program. REST e cel mai folosit stil pentru API-uri web: datele sunt resurse (useri, postări, comenzi), fiecare cu un URL, iar acțiunea e dată de metoda HTTP.
Ca frontender, consumi API-uri zilnic. Să înțelegi convențiile te ajută să le citești, să le folosești corect și să scrii Route Handlers care arată profesionist.
Convențiile — resursă + metodă
| Metodă | URL | Acțiune | Status la succes |
|---|---|---|---|
GET |
/posts |
listă | 200 |
GET |
/posts/42 |
un element | 200 (404 dacă lipsește) |
POST |
/posts |
creează | 201 + elementul creat |
PATCH |
/posts/42 |
modifică parțial | 200 |
PUT |
/posts/42 |
înlocuiește complet | 200 |
DELETE |
/posts/42 |
șterge | 204 fără body |
Reguli de nume:
- substantive la plural, nu verbe:
/posts, nu/getPostssau/createPost; - relații prin imbricare:
/posts/42/comments; - filtre, sortare, paginare în query string:
/posts?author=7&sort=-createdAt&page=2.
Răspunsuri și erori
// 200 — listă paginată
{ "data": [{ "id": 1, "title": "Salut" }], "page": 2, "totalPages": 9 }
// 422 — validare eșuată
{ "error": "validation", "fieldErrors": { "email": ["Email invalid"] } }| Situație | Status |
|---|---|
| date invalide | 400 / 422 |
| neautentificat | 401 |
| autentificat, fără drept | 403 |
| nu există | 404 |
| conflict (email deja folosit) | 409 |
| prea multe cereri | 429 |
| eroare internă | 500 — fără detalii interne în răspuns |
Un format de eroare consecvent în tot API-ul face frontend-ul mult mai simplu.
Paginare — tipuri și când
| Tip | Cum | Plusuri | Minusuri |
|---|---|---|---|
| offset | ?page=3&perPage=20 → OFFSET 40 LIMIT 20 |
simplu, sari direct la pagina 7 | lent pe tabele mari; elemente duplicate / sărite dacă se adaugă date între timp |
| cursor | ?after=<id-ultimul>&limit=20 |
rapid, stabil la date noi | nu poți sări la „pagina 7” |
Pagini numerotate (admin, căutare) → offset. Feed infinit (social, notificări) → cursor.
REST vs alternative
| REST | GraphQL | tRPC / Server Actions | |
|---|---|---|---|
| Formă | multe URL-uri, metode HTTP | un singur endpoint, clientul cere exact câmpurile | apelezi funcții de server direct din TS |
| Cache HTTP | natural | complicat | — |
| Tipuri client-server | prin OpenAPI / manual | din schemă | automate |
| Când | API public, consumatori diverși | multe clienți cu nevoi diferite | frontend + backend în același proiect TS |
Pe scurt
- Resurse la plural + metoda HTTP decide acțiunea; status-uri corecte (201, 204, 404, 422).
- Filtre și paginare în query string; un format de eroare consecvent.
- Offset pentru pagini numerotate, cursor pentru feed-uri infinite.