Fișă de referință API RESTful

REST (Representational State Transfer) este un stil arhitectural pentru proiectarea serviciilor web API prin HTTP.

Metode HTTP și semantică

---

Coduri de stare HTTP frecvente

Succes (2xx)

• 200 OK: Cerere reușită (corpul conține reprezentarea).
• 201 Created: Resursa a fost creată cu succes (antetul Location indică URI-ul).
• 202 Accepted: Cerere acceptată pentru procesare asincronă.
• 204 No Content: Acțiune reușită, fără corp în răspuns (comun la DELETE).

Erori client (4xx)

• 400 Bad Request: Sintaxă invalidă, parametri eronați sau eșec de validare.
• 401 Unauthorized: Autentificarea lipsește sau este invalidă.
• 403 Forbidden: Utilizatorul autentificat nu are permisiune de acces la resursă.
• 404 Not Found: URI-ul resursei nu există.
• 409 Conflict: Cererea intră în conflict cu starea curentă (ex. cheie unică duplicată).
• 422 Unprocessable Entity: Cerere validă sintactic ce a eșuat validarea semantică a domeniului.
• 429 Too Many Requests: Limita de rată (Rate Limit) a fost depășită.

Erori server (5xx)

• 500 Internal Server Error: Eroare generică netratată pe server.
• 502 Bad Gateway: Serverul upstream a returnat un răspuns invalid.
• 503 Service Unavailable: Server supraîncărcat sau în mentenanță.

---

Structură standard de eroare JSON

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The email address provided is already registered.",
    "details": [
      {
        "field": "email",
        "issue": "unique_constraint_violated"
      }
    ]
  }
}

---

Referințe

• Fișă de referință coduri de stare HTTP
• RFC 9110: Semantica HTTP