...
← Curs ASP.NET Core: toate lecțiile
Lecția 14 · POST

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.

De ce nu Count + 1

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}
1
Corpul cererii este citit într-un ProdusNou (fără id).
2
Serverul calculează id-ul: cel mai mare id este 3, deci noul id este 4.
3
Construiește Produs-ul complet și îl adaugă în listă.
4
Results.Created($"/produse/{id}", produs) trimite 201, antetul Location: /produse/4 și produsul ca JSON.

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 /produse
POST /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

CerereaRăspunsulLocation
POST /comenzi201 + comanda cu id și status/comenzi/98431
POST /utilizatori201 + contul (fără parolă)/utilizatori/512
POST /cos/produse201 + 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.

Exercițiul tău

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).
Ordinea contează: calculează id-ul, creează produsul, adaugă-l în listă, apoi întoarce rezultatul.

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);
Excelent! Continuă cu lecția următoare →
Program.csASP.NET Core
ConsolăSe încarcă...
Mediul de lucru se încarcă. Poți citi lecția între timp.
Rulează codul cu butonul de sus sau cu Ctrl + Enter / Cmd + Enter.
Parcursul tău Primul tău API cu ASP.NET Core Lecția 14 · Results.Created: 201 și antetul Location
Progres 0% 0 din 22
Lecția curentă 14 / 20 Post