Results.Created: 201 și antetul Location
Când un client creează ceva (un produs, o comandă, un cont), nu îi ajunge un „OK”. Vrea să știe ce s-a creat și unde îl găsește de acum înainte. Convenția REST pentru asta are trei părți: codul 201 Created, antetul Location cu adresa resursei noi și resursa însăși în corp. În ASP.NET Core le trimiți pe toate cu Results.Created.
Convenția pentru creare
Imaginează-ți că plasezi o comandă într-un magazin online. Aplicația trimite POST /comenzi, iar serverul răspunde:
HTTP/1.1 201 Created
Location: /comenzi/98431
Content-Type: application/json; charset=utf-8
{"id":98431,"total":349.90,"status":"plasata"}- 201 Created spune „am creat o resursă nouă”, mai precis decât 200;
- Location spune adresa la care clientul poate cere resursa de acum înainte (GET /comenzi/98431);
- corpul conține resursa creată, inclusiv ce a adăugat serverul (id-ul, statusul), ca să nu fie nevoie de încă o cerere.
Clientul trimite datele, serverul alege id-ul
Clientul nu trimite id-ul: serverul este cel care știe ce id-uri sunt ocupate. De aceea ai nevoie de două tipuri: unul pentru ce trimite clientul și unul pentru resursa completă.
record ProdusNou(string Nume, decimal Pret); // ce trimite clientul în corp record Produs(int Id, string Nume, decimal Pret); // resursa salvată, cu id
Pentru id, cea mai simplă soluție cu o listă în memorie este „cel mai mare id existent + 1”: produse.Max(p => p.Id) + 1. Bazele de date reale fac asta singure (coloane auto-increment), cum vei vedea la Entity Framework Core.
produse.Count + 1 pare la fel, dar greșește după o ștergere: dacă ai id-urile 1, 2, 3 și ștergi 2, Count + 1 dă 3, un id deja folosit. Max + 1 dă corect 4.
Results.Created în practică
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var produse = new List<Produs>
{
new(1, "Laptop", 3500m),
new(2, "Mouse", 99m),
new(3, "Monitor", 899m)
};
app.MapPost("/produse", (ProdusNou nou) =>
{
var id = produse.Max(p => p.Id) + 1;
var produs = new Produs(id, nou.Nume, nou.Pret);
produse.Add(produs);
return Results.Created($"/produse/{id}", produs);
});
app.Run();
record ProdusNou(string Nume, decimal Pret);
record Produs(int Id, string Nume, decimal Pret);
// POST /produse {"nume": "Căști", "pret": 199}POST /produse → 201 Created
Location: /produse/4
{"id":4,"nume":"Căști","pret":199}Laboratorul afișează automat antetul Location pentru răspunsurile 201, pe linia de sub status. Primul argument al lui Created este exact textul din Location.
Lista chiar s-a schimbat
Pentru că lista este creată o singură dată, la pornire, produsul adăugat de POST rămâne în ea pentru cererile următoare (până la repornirea serverului):
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var produse = new List<Produs>
{
new(1, "Laptop", 3500m),
new(2, "Mouse", 99m),
new(3, "Monitor", 899m)
};
app.MapGet("/produse", () => produse.Select(p => p.Nume));
app.MapPost("/produse", (ProdusNou nou) =>
{
var id = produse.Max(p => p.Id) + 1;
var produs = new Produs(id, nou.Nume, nou.Pret);
produse.Add(produs);
return Results.Created($"/produse/{id}", produs);
});
app.Run();
record ProdusNou(string Nume, decimal Pret);
record Produs(int Id, string Nume, decimal Pret);
// POST /produse {"nume": "Căști", "pret": 199}
// POST /produse {"nume": "Webcam", "pret": 249}
// GET /produsePOST /produse → 201 Created
Location: /produse/4
{"id":4,"nume":"Căști","pret":199}
POST /produse → 201 Created
Location: /produse/5
{"id":5,"nume":"Webcam","pret":249}
GET /produse → 200 OK
["Laptop","Mouse","Monitor","Căști","Webcam"]Al doilea POST primește id-ul 5, pentru că acum cel mai mare id este 4. GET /produse arată toate cele cinci nume.
Greșeli frecvente
- Întorci 200 la creare: funcționează, dar clientul nu află adresa resursei noi. Convenția este 201 + Location.
- Lași clientul să aleagă id-ul: doi clienți pot trimite același id; serverul trebuie să-l genereze.
- **Uiți produse.Add(produs)**: răspunsul arată bine, dar produsul nu e salvat, iar GET nu îl găsește.
- **Location greșit**: Results.Created("/produse", produs) trimite clientul la listă, nu la produsul nou. Include id-ul în adresă.
- **Max pe o listă goală** aruncă InvalidOperationException. Dacă lista poate fi goală, folosește produse.Count == 0 ? 1 : produse.Max(p => p.Id) + 1.
Created în aplicații reale
| Cererea | Răspunsul | Location |
|---|---|---|
| POST /comenzi | 201 + comanda cu id și status | /comenzi/98431 |
| POST /utilizatori | 201 + contul (fără parolă) | /utilizatori/512 |
| POST /cos/produse | 201 + linia din coș | /cos/produse/3 |
Aplicația client citește Location ca să deschidă direct pagina resursei noi, de exemplu „Comanda #98431 a fost plasată”, cu link spre detalii.
Adaugă crearea de produse. Lista pornește cu (1, Laptop, 3500), (2, Mouse, 99), (3, Monitor, 899). Declară record ProdusNou(string Nume, decimal Pret). POST /produse primește un ProdusNou, îi dă id-ul cel mai mare id + 1, îl adaugă în listă și întoarce Results.Created cu adresa /produse/{id}. GET /produse întoarce lista. Laboratorul trimite două POST-uri (Tastatură 199, apoi Boxă 249) și GET /produse.
- Declară record ProdusNou(string Nume, decimal Pret); lângă Produs.
- În POST /produse, calculează var id = produse.Max(p => p.Id) + 1;.
- Creează new Produs(id, nou.Nume, nou.Pret) și adaugă-l în listă.
- Întoarce Results.Created($"/produse/{id}", produs).
Soluția exercițiului
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var produse = new List<Produs>
{
new(1, "Laptop", 3500m),
new(2, "Mouse", 99m),
new(3, "Monitor", 899m)
};
app.MapGet("/produse", () => produse);
app.MapPost("/produse", (ProdusNou nou) =>
{
var id = produse.Max(p => p.Id) + 1;
var produs = new Produs(id, nou.Nume, nou.Pret);
produse.Add(produs);
return Results.Created($"/produse/{id}", produs);
});
app.Run();
record Produs(int Id, string Nume, decimal Pret);
record ProdusNou(string Nume, decimal Pret); 