Ce înseamnă un API bun — Construiește un REST API cu Laravel

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.