Recapitulare: primul tău API
Ai ajuns la finalul primului modul. În 19 lecții ai trecut de la un singur MapGet la un API CRUD complet, cu rute, constrângeri, query string, JSON, coduri de status și antete. În această recapitulare treci încă o dată prin toate, vezi greșelile cele mai frecvente adunate la un loc și construiești API-ul unei biblioteci.
Structura Program.cs, pe scurt
using Microsoft.AspNetCore.Mvc; // doar dacă folosești [FromHeader] și altele
var builder = WebApplication.CreateBuilder(args); // 1. configurare și servicii
var app = builder.Build(); // 2. aplicația
var carti = new List<Carte> { /* date inițiale */ }; // „baza de date” în memorie
app.MapGet("/carti", () => carti); // 3. rute
app.Run(); // 4. pornește serverul
record Carte(int Id, string Titlu, string Autor, int An); // 5. tipurile, la finalOrdinea este mereu aceeași: builder, Build, date și rute, Run, apoi tipurile. Dacă respecți ordinea, eviți jumătate din erorile începătorilor.
Tabel-sinteză al modulului
| Ce vrei | Cum scrii | Lecția |
|---|---|---|
| un endpoint GET | app.MapGet("/cale", () => ...) | 1–4 |
| JSON în răspuns | întorci un obiect sau un record | 5, 9 |
| valoare din cale | "/carti/{id}" + (int id) | 6 |
| doar numere în cale | {id:int}, {id:int:min(1)} | 7 |
| filtre opționale | (string? autor, int pagina = 1) din query | 8 |
| date în memorie | List<T> + LINQ | 10 |
| alegi codul de status | Results.Ok, NotFound, BadRequest, Conflict | 11–12 |
| primești JSON | MapPost cu un parametru record | 13 |
| creezi | Results.Created("/carti/4", carte) | 14 |
| actualizezi | MapPut + FindIndex | 16 |
| ștergi | MapDelete + Results.NoContent() | 17 |
| antete | [FromHeader(Name = "X-...")], raspuns.Headers[...] | 18 |
Filtru opțional din query
Un singur endpoint poate întoarce fie toată lista, fie doar o parte, după un parametru opțional. Aici autor este string?: dacă lipsește din query, este null și întoarcem tot.
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var carti = new List<Carte>
{
new(1, "Ion", "Liviu Rebreanu", 1920),
new(2, "Pădurea spânzuraților", "Liviu Rebreanu", 1922),
new(3, "Enigma Otiliei", "George Călinescu", 1938)
};
app.MapGet("/carti", (string? autor) =>
autor is null ? carti : carti.Where(c => c.Autor.Contains(autor)).ToList());
app.Run();
record Carte(int Id, string Titlu, string Autor, int An);
record CarteNoua(string Titlu, string Autor, int An);
// GET /carti?autor=Călinescu
// GET /carti?autor=EminescuGET /carti?autor=Călinescu → 200 OK
[{"id":3,"titlu":"Enigma Otiliei","autor":"George Călinescu","an":1938}]
GET /carti?autor=Eminescu → 200 OK
[]Contains caută textul oriunde în numele autorului, deci Călinescu găsește „George Călinescu”. Când nu se potrivește nimic, răspunsul este un tablou gol [] cu 200, nu 404: colecția există, doar că filtrul nu a găsit nimic.
carti este List<Carte>, iar Where întoarce IEnumerable<Carte>. Cele două ramuri ale ternarului trebuie să aibă același tip, așa că transformăm rezultatul filtrat în listă cu ToList().
Greșelile frecvente ale modulului
| Simptomul | Cauza | Soluția |
|---|---|---|
| eroarea CS8803 la compilare | un record e scris înaintea codului | mută tipurile după app.Run(); |
| nicio cerere nu primește răspuns | lipsește app.Run(); | adaugă-l la finalul instrucțiunilor |
| 400 în loc de 404 pentru /carti/abc | ruta nu are constrângere | folosește {id:int} |
| 200 cu null | întorci direct rezultatul lui FirstOrDefault | is null ? Results.NotFound() : Results.Ok(x) |
| 405 Method Not Allowed | metoda cererii nu are endpoint pe acea cale | verifică MapPost/MapPut/MapDelete |
| 415 Unsupported Media Type | corpul nu este JSON | trimite Content-Type: application/json |
| 500 AmbiguousMatchException | două rute la fel | șterge duplicatul sau adaugă constrângeri |
| 500 la Max | lista e goală | Count == 0 ? 1 : Max(...) + 1 |
Ce urmează
În modulul următor, API-uri REST cu Minimal APIs, transformi ce știi într-un API profesionist: principiile REST, grupuri de rute cu MapGroup, validarea datelor și erorile în format standard (ProblemDetails), TypedResults, paginare, sortare și căutare, PATCH și filtre de endpoint.
- lista în memorie devine un serviciu injectat (dependency injection);
- validarea manuală devine validare cu atribute și ProblemDetails;
- datele trec într-o bază de date reală cu Entity Framework Core.
Construiește API-ul unei biblioteci. Lista pornește cu: (1, Ion, Liviu Rebreanu, 1920), (2, Pădurea spânzuraților, Liviu Rebreanu, 1922), (3, Enigma Otiliei, George Călinescu, 1938). Ai nevoie de: GET /carti cu filtrul opțional autor din query (cărțile al căror autor conține textul dat), GET /carti/{id:int} (200 sau 404 cu mesajul Cartea {id} nu există), POST /carti (400 cu mesajul Titlul este obligatoriu dacă titlul e gol, altfel 201 cu Location: /carti/{id}) și DELETE /carti/{id:int} (204 sau 404). Laboratorul trimite: GET /carti, GET /carti?autor=Rebreanu, un POST valid (Baltagul, Mihail Sadoveanu, 1930), un POST cu titlul gol, DELETE /carti/1 și GET /carti/1.
- Record-urile Carte și CarteNoua sunt deja declarate la finalul fișierului.
- GET /carti primește string? autor; fără autor întoarce tot, cu autor întoarce carti.Where(c => c.Autor.Contains(autor)).ToList().
- GET /carti/{id:int} întoarce 200 sau 404 cu mesajul cerut.
- POST /carti verifică titlul cu string.IsNullOrWhiteSpace înainte să adauge, apoi întoarce Results.Created.
- DELETE /carti/{id:int} întoarce 204 sau 404.
Soluția exercițiului
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var carti = new List<Carte>
{
new(1, "Ion", "Liviu Rebreanu", 1920),
new(2, "Pădurea spânzuraților", "Liviu Rebreanu", 1922),
new(3, "Enigma Otiliei", "George Călinescu", 1938)
};
app.MapGet("/carti", (string? autor) =>
autor is null ? carti : carti.Where(c => c.Autor.Contains(autor)).ToList());
app.MapGet("/carti/{id:int}", (int id) =>
{
var carte = carti.FirstOrDefault(c => c.Id == id);
return carte is null ? Results.NotFound($"Cartea {id} nu există") : Results.Ok(carte);
});
app.MapPost("/carti", (CarteNoua noua) =>
{
if (string.IsNullOrWhiteSpace(noua.Titlu))
{
return Results.BadRequest("Titlul este obligatoriu");
}
var id = carti.Count == 0 ? 1 : carti.Max(c => c.Id) + 1;
var carte = new Carte(id, noua.Titlu, noua.Autor, noua.An);
carti.Add(carte);
return Results.Created($"/carti/{id}", carte);
});
app.MapDelete("/carti/{id:int}", (int id) =>
carti.RemoveAll(c => c.Id == id) == 0 ? Results.NotFound() : Results.NoContent());
app.Run();
record Carte(int Id, string Titlu, string Autor, int An);
record CarteNoua(string Titlu, string Autor, int An); 