Răspunsuri JSON: obiecte întoarse din endpoint
Până acum serverul tău a întors doar texte. O aplicație mobilă însă are nevoie de date structurate: numele produsului, prețul, dacă e în stoc. Formatul în care API-urile trimit astfel de date este JSON. Vestea bună: în ASP.NET Core nu trebuie să scrii JSON de mână; întorci un obiect C#, iar framework-ul îl transformă singur.
Ce este JSON
JSON (JavaScript Object Notation) este un format text pentru date, ușor de citit și de oameni, și de programe. Aproape orice API web modern vorbește JSON, pentru că îl înțeleg toate limbajele: JavaScript în browser, Kotlin și Swift pe telefon, Python, Java, C#.
{
"nume": "Laptop",
"pret": 3500,
"inStoc": true,
"reducere": null,
"culori": ["negru", "argintiu"]
}| Tip JSON | Exemplu | Tipul C# din care vine de obicei |
|---|---|---|
| obiect | {"nume": "Laptop"} | un obiect (clasă, record, obiect anonim) |
| tablou | ["negru", "argintiu"] | tablou, List<T> |
| text | "Laptop" | string |
| număr | 3500, 49.5 | int, decimal, double |
| boolean | true, false | bool |
| nimic | null | null |
Un obiect JSON este o listă de perechi "cheie": valoare între acolade; un tablou este o listă de valori între paranteze drepte. Cheile sunt mereu între ghilimele.
Întorci un obiect, primești JSON
Când funcția unui endpoint întoarce un obiect (nu un string), ASP.NET Core îl serializează automat în JSON, cu biblioteca System.Text.Json. Cel mai rapid mod de a crea un obiect este un obiect anonim, new { ... }, pe care îl știi din cursul de C#:
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/produs", () => new { Nume = "Laptop", Pret = 3500, InStoc = true });
app.Run();
// GET /produsGET /produs → 200 OK
{"nume":"Laptop","pret":3500,"inStoc":true}Numere, null, tablouri și ordinea proprietăților
Iată un obiect cu mai multe tipuri de valori și un endpoint care întoarce direct un tablou:
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/oferta", () => new
{
Produs = "Căști",
Pret = 199.90m,
Rating = 4.5,
Reducere = (string?)null,
Culori = new[] { "negru", "alb" }
});
app.MapGet("/categorii", () => new[] { "Laptopuri", "Telefoane", "Accesorii" });
app.Run();
// GET /oferta
// GET /categoriiGET /oferta → 200 OK
{"produs":"Căști","pret":199.90,"rating":4.5,"reducere":null,"culori":["negru","alb"]}
GET /categorii → 200 OK
["Laptopuri","Telefoane","Accesorii"]- ordinea proprietăților din JSON este ordinea în care le-ai scris în C#;
- un decimal își păstrează zecimalele scrise: 199.90m → 199.90; un double se scrie cât de scurt se poate: 4.5;
- o valoare null apare ca null (cheia nu dispare);
- un tablou C# devine un tablou JSON, iar un endpoint poate întoarce direct un tablou, nu doar un obiect.
În laborator, textele cu diacritice apar exact cum le-ai scris ("Căști"), ca să fie ușor de citit. Într-o aplicație ASP.NET Core reală, System.Text.Json escapează implicit caracterele non-ASCII, așa că același răspuns ar conține "C\u0103\u0219ti". Pentru client nu e nicio diferență: orice program care citește JSON-ul obține tot „Căști”.
Text sau JSON? Antetul Content-Type
Clientul află ce fel de date are în corp din antetul de răspuns **Content-Type**. ASP.NET Core îl setează singur, după ce întoarce endpoint-ul. Ca să-l vezi în laborator, adaugă cuvântul type după calea din comentariu:
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/text", () => "Laptop");
app.MapGet("/json", () => new { Nume = "Laptop" });
app.Run();
// GET /text type
// GET /json typeGET /text → 200 OK (text/plain; charset=utf-8)
Laptop
GET /json → 200 OK (application/json; charset=utf-8)
{"nume":"Laptop"}| Ce întorci | Content-Type | Corpul |
|---|---|---|
| un string | text/plain; charset=utf-8 | textul, fără ghilimele |
| un obiect sau un tablou | application/json; charset=utf-8 | JSON |
charset=utf-8 spune clientului cum sunt codificate caracterele, deci și diacriticele. O aplicație mobilă citește application/json și știe că poate transforma corpul într-un obiect al ei.
Greșeli frecvente
- Scrii JSON de mână într-un string: () => "{\"nume\": \"Laptop\"}" trimite un text cu Content-Type: text/plain, nu JSON. Întoarce un obiect și lasă framework-ul să facă JSON-ul.
- Te aștepți la PascalCase în JSON: Nume din C# apare ca nume. Clientul (de exemplu JavaScript) trebuie să citească nume.
- **Crezi că lipsește o proprietate null**: ea apare ca "reducere":null.
- Ghilimele simple: JSON acceptă doar ghilimele duble, 'nume' nu este JSON valid.
Unde vezi JSON în viața reală
| Aplicația | Ce cere | Ce primește |
|---|---|---|
| magazin online | GET /produse/15 | {"nume":"Laptop","pret":3500,"inStoc":true} |
| aplicație meteo | GET /vreme/cluj | {"oras":"Cluj","temperatura":21.5} |
| aplicație de livrări | GET /restaurante | un tablou de obiecte, câte unul pentru fiecare restaurant |
În lecțiile următoare vei înlocui obiectele anonime cu tipuri proprii (record), ca să poți refolosi aceeași formă a datelor în mai multe endpoint-uri.
Construiește două endpoint-uri JSON pentru magazin. GET /produs întoarce un obiect anonim cu proprietățile Nume = Laptop, Pret = 3500 și InStoc = true, în această ordine. GET /taguri întoarce un tablou cu trei texte: nou, reducere, livrare gratuită. Laboratorul trimite cele două cereri, a doua cu afișarea antetului Content-Type.
- Adaugă GET /produs care întoarce new { Nume = "Laptop", Pret = 3500, InStoc = true }.
- Adaugă GET /taguri care întoarce un tablou de stringuri cu nou, reducere, livrare gratuită.
- Nu scrie JSON de mână: întoarce obiectul și tabloul, iar ASP.NET Core face restul.
Soluția exercițiului
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/produs", () => new { Nume = "Laptop", Pret = 3500, InStoc = true });
app.MapGet("/taguri", () => new[] { "nou", "reducere", "livrare gratuită" });
app.Run(); 