Construiești un API mic care ține evidența plantelor de udat: le listează, găsește una după număr și adaugă plante noi. Nu are interfață: îi trimiți cereri HTTP, iar el răspunde cu JSON. Așa arată o cerere și răspunsul ei:
al doilea terminal
curl -i http://localhost:5290/plante/2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"id":2,"nume":"Cactus","udaLaZile":21}
Cu verde e comanda tastată. Pentru lecție ai nevoie de SDK-ul .NET 8 și de un terminal. Proiectul îl creezi cu șablonul gol, web:
terminal
dotnet new web -n Plantecd Plantedotnet run
La pornire, dotnet run afișează adresa pe care ascultă, de exemplu http://localhost:5290. Portul tău poate fi altul: îl găsești și în Properties/launchSettings.json.
să legi o adresă și o metodă HTTP de o funcție, cu MapGet și MapPost
să citești parametri din adresă și obiecte JSON din corpul cererii
să răspunzi cu codul de stare potrivit: 200, 201, 400, 404
să testezi API-ul din terminal, cu curl
Pasul 2 din 5
Ce se întâmplă la fiecare cerere
Înlocuiește conținutul din Program.cs cu codul de mai jos. Urmărești întâi pornirea, apoi două cereri: GET /plante/2 și un POST care adaugă o plantă.
Program.cs
var builder = WebApplication.CreateBuilder(args);var app = builder.Build();var plante = new List<Planta>{new(1, "Ficus", 7),new(2, "Cactus", 21)};int urmatorulId = 3;app.MapGet("/plante", () => plante);app.MapGet("/plante/{id:int}", (int id) =>{var p = plante.Find(x => x.Id == id);return p isnull ? Results.NotFound() : Results.Ok(p);});app.MapPost("/plante", (PlantaNoua nou) =>{if (string.IsNullOrWhiteSpace(nou.Nume))return Results.BadRequest("Numele e obligatoriu.");var p = new Planta(urmatorulId++, nou.Nume, nou.UdaLaZile); plante.Add(p);return Results.Created($"/plante/{p.Id}", p);});app.Run();recordPlanta(int Id, string Nume,int UdaLaZile);recordPlantaNoua(string Nume,int UdaLaZile);
Stare
Terminal și răspunsuri
Linia 1.builder adună configurarea aplicației: setări, servicii, loguri. Încă nu ascultă nimic.
Linia 2.Build produce aplicația, app, pe care o vei configura cu rute.
Linia 4. Lista plantelor stă în memorie, într-o variabilă obișnuită. Pornește cu două plante.
Linia 9. Următoarea plantă nouă va primi numărul 3.
Linia 11.MapGet doar înregistrează o rută: „la GET /plante, rulează funcția asta”. Funcția nu rulează acum. La fel fac liniile 13 și 21 pentru celelalte două rute.
Linia 33.app.Run() pornește serverul și blochează programul: de acum așteaptă cereri.
Linia 13. Sosește GET /plante/2. Adresa se potrivește cu /plante/{id:int}, iar „2” devine parametrul id.
Linia 15.Find caută planta cu numărul 2 și găsește cactusul.
Linia 16.p nu e null, deci ternarul alege ramura de după :.
Linia 18.Results.Ok(p) dă codul 200 și transformă planta în JSON. Numele proprietăților încep cu literă mică.
Linia 21. Sosește un POST /plante cu JSON în corp. ASP.NET Core îl citește și construiește obiectul nou.
Linia 23. Numele nu e gol, deci nu răspundem cu 400.
Linia 26. Planta nouă primește numărul 3. urmatorulId++ folosește valoarea, apoi o crește la 4.
Linia 28. Planta intră în listă. O vor vedea toate cererile următoare.
Linia 29.Results.Created dă codul 201 și antetul Location, adresa noii plante.
Gata. Serverul rulează în continuare și așteaptă alte cereri, până apeși Ctrl+C.
Prezice răspunsul
Serverul rulează, iar lista are doar Ficus și Cactus. Trimiți GET /plante/9. Ce primești?
Răspuns: 404 Not Found, fără corp.
Ruta se potrivește, deci funcția rulează. Find nu găsește planta și întoarce null, iar ternarul alege Results.NotFound(). Serverul merge mai departe.
Pasul 3 din 5
Rute, răspunsuri și teste din terminal
Trei idei care apar în orice API, oricât de mare ar fi. La final, două greșeli care te pot costa o oră de căutat.
1
O rută: metodă, adresă, funcție
Metodele HTTP și metodele Map corespunzătoare
Metoda
Folosită pentru
MapGet
citești date
MapPost
creezi ceva nou
MapPut
înlocuiești ceva existent
MapDelete
ștergi
Acoladele din adresă marchează un parametru: {id:int} prinde orice număr întreg și îl dă funcției ca int id, după nume. Partea :int e o constrângere: /plante/abc nu se potrivește deloc cu ruta.
Un parametru care nu apare în adresă, ca PlantaNoua nou la POST, e citit din corpul cererii, ca JSON.
2
Codul de stare spune ce s-a întâmplat
Coduri de stare HTTP și metodele Results
Cod
Când
200Ok
totul a mers, iată datele
201Created
am creat ceva, iată adresa lui
204NoContent
am reușit, n-am ce trimite
400BadRequest
cererea ta e greșită
404NotFound
nu există
Când funcția întoarce direct un obiect, ca la GET /plante, răspunsul e automat 200 cu JSON. Când răspunsul depinde de date, folosești Results. Toate ramurile unei funcții trebuie să întoarcă un rezultat de același fel.
3
Testezi cu curl
Lasă serverul pornit și deschide un al doilea terminal. -i afișează și codul de stare, -X alege metoda, -H adaugă un antet, iar -d trimite corpul cererii.
Pe Windows, în PowerShell, scrie curl.exe în loc de curl. În Visual Studio și Rider poți folosi și un fișier .http, cu cererile scrise una sub alta.
Capcană: ai uitat app.Run()
Fără ultima linie, programul înregistrează rutele și se termină imediat. dotnet run afișează doar „Building...”, fără nicio eroare. Abia curl îți arată că nu ascultă nimeni:
Program.cs
var builder = WebApplication.CreateBuilder(args);var app = builder.Build();app.MapGet("/plante", () => "Ficus");
curl: (7) Failed to connect to localhost port 5290 after 0 ms: Couldn't connect to server
Repară adăugând app.Run(); după toate rutele. Tot ce scrii după el nu se mai execută cât timp serverul rulează.
Capcană: POST fără Content-Type
Trimiți JSON corect, dar uiți antetul. Fără el, curl declară alt tip de conținut, iar ASP.NET Core refuză să citească un obiect din el:
curl -i -X POST http://localhost:5290/plante -d '{"nume":"Aloe","udaLaZile":14}'HTTP/1.1 415 Unsupported Media Type
Content-Length: 0
Repară adăugând -H "Content-Type: application/json". Codul 415 înseamnă mereu „nu înțeleg formatul în care mi-ai trimis datele”.
Pasul 4 din 5
Verifică-te
Cinci întrebări despre API-ul de plante. După fiecare răspuns vezi imediat de ce e așa.
1 din 5 · Prezice răspunsul
Trimiți GET /plante/abc. Ce cod de stare primești?
Răspuns: 404 Not Found.
Constrângerea :int face ca „abc” să nu se potrivească cu ruta. Nicio rută nu prinde adresa, iar ASP.NET Core răspunde singur cu 404. Funcția ta nici nu rulează.
2 din 5 · Alege varianta
Ce cod de stare e potrivit după ce ai creat o plantă nouă?
Răspuns: 201 Created, cu antetul Location.
201 spune clar că s-a creat o resursă, iar Location îi arată clientului unde o găsește. 204 se potrivește la ștergere, când nu ai ce trimite înapoi.
3 din 5 · Prezice răspunsul
Trimiți un POST /plante corect, cu antet, dar cu corpul {"nume":"","udaLaZile":5}. Ce primești?
Răspuns: 400 Bad Request și textul „Numele e obligatoriu.”
JSON-ul e valid, deci obiectul se construiește. Verificarea de la linia 23 găsește numele gol și oprește funcția înainte de Add.
4 din 5 · Alege varianta
Când rulează funcția scrisă în app.MapGet("/plante", …)?
Răspuns: la fiecare cerere GET /plante.
MapGet doar leagă adresa de funcție. Funcția rulează la fiecare cerere potrivită, oricât de multe ar fi.
5 din 5 · Prezice răspunsul
Ai adăugat Monstera cu un POST, apoi ai oprit serverul cu Ctrl+C și l-ai pornit din nou. Câte plante întoarce acum GET /plante?
Răspuns: 2, Ficus și Cactus.
Lista trăiește în memoria procesului. La repornire, programul rulează din nou de la linia 1 și o construiește iar cu cele două plante inițiale. Ca datele să rămână, ai nevoie de o bază de date.
Pasul 5 din 5
Ce ai învățat
Un Minimal API leagă o metodă HTTP și o adresă de o funcție: MapGet, MapPost, MapDelete.
Parametrii vin din adresă ({id:int}) sau, ca JSON, din corpul cererii.
Codul de stare spune clientului ce s-a întâmplat: 200, 201, 204, 400, 404.
app.Run() pornește serverul. Datele ținute într-o listă se pierd la repornire.
Programul complet
Versiunea finală adaugă ștergerea. RemoveAll întoarce câte plante a scos: dacă a scos măcar una, răspunsul e 204, altfel 404.