MyCodeSchool

Pasul 1 din 5

ASP.NET Core

Pasul 1 din 5 · Ce construiești

  • ASP.NET Core
  • Începător
  • 13 minute

Primul tău API cu ASP.NET Core

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.

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 is null        ? 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();record Planta(int Id, string Nume,    int UdaLaZile);record PlantaNoua(string Nume,    int UdaLaZile);

Stare

Terminal și răspunsuri


      

  1. Linia 1. builder adună configurarea aplicației: setări, servicii, loguri. Încă nu ascultă nimic.
  2. Linia 2. Build produce aplicația, app, pe care o vei configura cu rute.
  3. Linia 4. Lista plantelor stă în memorie, într-o variabilă obișnuită. Pornește cu două plante.
  4. Linia 9. Următoarea plantă nouă va primi numărul 3.
  5. 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.
  6. Linia 33. app.Run() pornește serverul și blochează programul: de acum așteaptă cereri.
  7. Linia 13. Sosește GET /plante/2. Adresa se potrivește cu /plante/{id:int}, iar „2” devine parametrul id.
  8. Linia 15. Find caută planta cu numărul 2 și găsește cactusul.
  9. Linia 16. p nu e null, deci ternarul alege ramura de după :.
  10. Linia 18. Results.Ok(p) dă codul 200 și transformă planta în JSON. Numele proprietăților încep cu literă mică.
  11. Linia 21. Sosește un POST /plante cu JSON în corp. ASP.NET Core îl citește și construiește obiectul nou.
  12. Linia 23. Numele nu e gol, deci nu răspundem cu 400.
  13. Linia 26. Planta nouă primește numărul 3. urmatorulId++ folosește valoarea, apoi o crește la 4.
  14. Linia 28. Planta intră în listă. O vor vedea toate cererile următoare.
  15. Linia 29. Results.Created dă codul 201 și antetul Location, adresa noii plante.
  16. 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.

O rută: metodă, adresă, funcție

Metodele HTTP și metodele Map corespunzătoare
MetodaFolosită pentru
MapGetcitești date
MapPostcreezi 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.

Codul de stare spune ce s-a întâmplat

Coduri de stare HTTP și metodele Results
CodCând
200 Oktotul a mers, iată datele
201 Createdam creat ceva, iată adresa lui
204 NoContentam reușit, n-am ce trimite
400 BadRequestcererea ta e greșită
404 NotFoundnu 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.

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.

al doilea terminal
curl -i http://localhost:5290/plante/2curl -i -X POST http://localhost:5290/plante \  -H "Content-Type: application/json" \  -d '{"nume":"Monstera","udaLaZile":5}'

Răspunsul la POST, fără antetele Date și Server

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
Location: /plante/3
Transfer-Encoding: chunked

{"id":3,"nume":"Monstera","udaLaZile":5}

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

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.

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 is null        ? 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.MapDelete("/plante/{id:int}", (int id) =>    plante.RemoveAll(x => x.Id == id) > 0        ? Results.NoContent()        : Results.NotFound());app.Run();record Planta(int Id, string Nume,    int UdaLaZile);record PlantaNoua(string Nume,    int UdaLaZile);

curl -i -X DELETE …/plante/1, de două ori

HTTP/1.1 204 No Content

HTTP/1.1 404 Not Found

Continuă cu