Ce înseamnă un API bun

Lectură estimată: 4 minute

Estimare pentru text, la un ritm de 180 de cuvinte pe minut. Timpul pentru analizarea codului, exerciții și proiecte se adaugă separat și depinde de ritmul tău.

Problema pe care o vei rezolva: Contract API pentru listare și creare

API demonstrativ: GET /api/services cu paginare; POST /api/services pentru un rol autorizat. Intrări de test: title valid, title gol, sort necunoscut, utilizator fără drepturi.

Rezultatul urmărit

Scrie contractul JSON și erorile înaintea controllerului. Folosește Resources pentru câmpurile publice și verifică efectele în baza de date pentru fiecare cerere.

Cum recunoști o soluție corectă

Listarea nu expune câmpuri private. Sortarea folosește o listă permisă. Cererea invalidă și cea neautorizată nu creează servicii; răspunsul are format consecvent.

Parcurge lecțiile în ordine și păstrează exercițiile în registrul descărcabil. Ultima lecție include atelierul de 40 de minute în care combini conceptele și testezi o variație a situației inițiale. Exemplele comerciale sunt fictive; nu reprezintă rezultate ale unor clienți.

Un API bun e previzibil: cine îl folosește poate ghici cum funcționează un endpoint nou după ce a văzut două. Asta înseamnă convenții consecvente — verbe HTTP, coduri de status, structura răspunsului, denumirea resurselor — respectate peste tot.

Principii REST

Resursele sunt substantive la plural: `/articole`, `/comenzi`.
Verbele HTTP dau acțiunea: GET (citește), POST (creează), PUT/PATCH (actualizează), DELETE (șterge).
`GET /articole` = listă, `GET /articole/1` = unul, `POST /articole` = creează.
Fără verbe în URL: nu `/getArticole` sau `/articole/delete/1`.

Coduri de status corecte

200 OK — succes cu corp.
201 Created — resursă creată (POST).
204 No Content — succes fără corp (DELETE).
400 Bad Request — cererea e malformată.
401 / 403 — neautentificat / neautorizat.
404 Not Found — resursa nu există.
422 Unprocessable Entity — validare eșuată.
500 — eroare de server (bug).

Structura răspunsului

// consecvent, mereu:
{
  "data": { ... }          // sau [ ... ] pentru liste
}
// pentru liste paginate:
{
  "data": [ ... ],
  "meta": { "current_page": 1, "total": 137, "per_page": 15 },
  "links": { "next": "...", "prev": null }
}

Versionare

Pune versiunea în URL de la început: `/api/v1/articole`. Chiar dacă nu ai încă v2, structura permite să introduci schimbări incompatibile fără să strici clienții existenți.

Exercițiu

Proiectează pe hârtie API-ul pentru un blog: listează toate endpoint-urile (metodă + cale) pentru articole și comentarii, cu codul de status de succes pentru fiecare. Verifică: doar substantive la plural, verbe HTTP pentru acțiuni.

Greșeli frecvente

Verbe în URL (`/createArticol`).
Întorci mereu 200, chiar și la erori (clientul nu poate distinge).
Structură de răspuns diferită de la un endpoint la altul.
Nu versionezi și primul breaking change strică toți clienții.

De reținut

Resurse = substantive la plural; acțiune = verb HTTP.
Coduri de status corecte: 201, 204, 404, 422, nu doar 200/500.
Structură de răspuns consecventă (data / meta / links).
Versionează din prima: /api/v1/.

Pe scurt

Un API previzibil respectă convențiile REST peste tot: URL-uri de resurse, verbe HTTP, coduri de status corecte, răspunsuri uniforme.

Contract API stabil pentru client

Un API bun definește resursele, statusurile, erorile și paginarea. Clientul nu trebuie să ghicească dacă o operație a reușit dintr-un mesaj în limba română. Pentru laborator, resursa cerere are id, serviciu și status, iar câmpurile interne nu sunt expuse. Metoda HTTP și răspunsul trebuie să aibă sens consecvent. Autentificarea și autorizarea se verifică pentru fiecare endpoint care cere acces, nu doar la login.

Exemplu de lucru

GET /api/v1/requests → listă paginată
POST /api/v1/requests → 201 + resursa creată
GET /api/v1/requests/42 → 200 sau eroare conform accesului
PATCH /api/v1/requests/42 → schimbare permisă
Exemplu: {"data":{"id":42,"service":"revizie","status":"new"}}

Interpretarea rezultatului

Un răspuns 200 cu textul „nu ai acces” contrazice contractul de status dacă aplicația a stabilit 403 pentru refuz. Păstrează documentația și testele sincronizate. Nu expune adrese sau note interne doar pentru că modelul le serializează implicit.

Exercițiu de consolidare

Definește un răspuns de eroare pentru status invalid și unul pentru resursă inaccesibilă, fără a divulga date suplimentare.

Aplicație practică

Sarcina

Definește contractul unui API de servicii.

Rezolvare orientativă și verificare

Descrie resurse, metode, statusuri, paginare și exemplu de eroare înainte de implementare.

Greșeală de evitat

Un contract stabil este mai util decât endpoint-uri construite ad-hoc.

Documentație și surse

Documentația Laravel 11 — versiunea aplicației demonstrative — Laravel
OWASP Top 10 — OWASP