Antete HTTP: citești și scrii headere
Pe lângă cale și corp, fiecare cerere și fiecare răspuns HTTP poartă antete (headers): mici perechi Nume: valoare cu informații despre mesaj. Ele spun ce format au datele, în ce limbă vrea utilizatorul răspunsul, cine este utilizatorul. În lecția aceasta înveți să citești un antet al cererii și să adaugi antete proprii în răspuns.
Ce sunt antetele
Un antet este o linie Nume: valoare între prima linie a mesajului și corp. Ai văzut deja câteva:
GET /produse HTTP/1.1 Host: magazin.ro Accept-Language: ro-RO User-Agent: MagazinApp/2.1 (Android 14) Authorization: Bearer eyJhbGciOi... X-Limba: ro
| Antet | În | La ce folosește |
|---|---|---|
| Content-Type | cerere și răspuns | formatul corpului (application/json) |
| Authorization | cerere | dovada că ești autentificat (în modulul de securitate) |
| User-Agent | cerere | ce aplicație sau browser trimite cererea |
| Accept-Language | cerere | limbile preferate de utilizator |
| Location | răspuns | adresa unei resurse create (la 201) |
| X-... | oricare | antete proprii ale aplicației, de exemplu X-Total-Count |
Numele antetelor nu țin cont de literele mari și mici: x-limba și X-Limba sunt același antet. Prefixul X- este o convenție veche pentru antete proprii; îl vei vedea des în API-uri.
Citești un antet cu [FromHeader]
Ca să primești un antet ca parametru al endpoint-ului, îi pui atributul [FromHeader]. Atributul se află în namespace-ul Microsoft.AspNetCore.Mvc, care nu e inclus automat, deci adaugi using Microsoft.AspNetCore.Mvc; la începutul fișierului:
using Microsoft.AspNetCore.Mvc;
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/salut", ([FromHeader(Name = "X-Limba")] string? limba) =>
limba == "en" ? "Hello!" : "Salut!");
app.Run();
// GET /salut header=X-Limba:en
// GET /salut header=X-Limba:ro
// GET /salutGET /salut → 200 OK Hello! GET /salut → 200 OK Salut! GET /salut → 200 OK Salut!
În laborator, adaugi un antet unei cereri de test cu header=Nume:valoare (fără spații) după cale: // GET /salut header=X-Limba:en. În Postman sau în fișierul .http scrii antetul pe un rând separat, sub adresă.
Dacă declari parametrul fără ? (string limba), antetul devine obligatoriu, iar o cerere fără el primește 400, ca la query string.
Scrii antete în răspuns cu HttpResponse
Ca să adaugi un antet în răspuns, ceri în endpoint un parametru de tip HttpResponse. ASP.NET Core îl completează singur cu răspunsul cererii curente (nu vine din cerere, ci din framework):
using Microsoft.AspNetCore.Mvc;
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", (HttpResponse raspuns) =>
{
raspuns.Headers["X-Total-Count"] = produse.Count.ToString();
return produse;
});
app.Run();
record Produs(int Id, string Nume, decimal Pret);
// GET /produse show=X-Total-CountGET /produse → 200 OK
X-Total-Count: 3
[{"id":1,"nume":"Laptop","pret":3500},{"id":2,"nume":"Mouse","pret":99},{"id":3,"nume":"Monitor","pret":899}]- raspuns.Headers["X-Total-Count"] = ... adaugă (sau înlocuiește) antetul; valoarea este un text, de aceea Count.ToString();
- corpul rămâne lista de produse, ca înainte;
- show=X-Total-Count din comentariu îi cere laboratorului să afișeze acel antet sub linia de status.
X-Total-Count este un antet folosit des la paginare: corpul are doar pagina curentă (de exemplu 20 de produse), iar antetul spune câte sunt în total (de exemplu 5.000), ca aplicația să poată desena butoanele de pagini.
Antet sau query?
| Pune informația în | Când | Exemple |
|---|---|---|
| cale sau query | descrie ce resursă vrei | /produse/15, ?pagina=2 |
| antet | descrie contextul cererii, același pentru multe cereri | limba, versiunea aplicației, autentificarea, formatul |
Regula practică: dacă utilizatorul ar vrea să copieze adresa și s-o trimită unui prieten, informația merge în URL. Dacă ține de aplicația sau de contul lui, merge într-un antet.
Greșeli frecvente
- **Uiți using Microsoft.AspNetCore.Mvc;**: compilatorul nu găsește FromHeader (eroarea CS0246, „The type or namespace name 'FromHeaderAttribute' could not be found”).
- **Uiți Name = ...**: fără el, ASP.NET Core caută un antet cu numele parametrului (limba), nu X-Limba.
- Pui parolele sau tokenurile în query în loc de antet: adresele ajung în istoricul browserului și în loguri. Datele sensibile merg în antetul Authorization.
- Scrii un număr direct: raspuns.Headers["X-Total-Count"] = produse.Count nu compilează; valoarea trebuie să fie text.
Adaugă două endpoint-uri care lucrează cu antete. GET /salut citește antetul opțional X-Limba și răspunde Hello! pentru en, altfel Salut! (inclusiv când antetul lipsește). GET /produse întoarce lista celor trei produse și scrie în răspuns antetul X-Total-Count cu numărul lor. Laboratorul trimite /salut cu X-Limba: en, /salut fără antet și /produse, afișând X-Total-Count.
- În GET /salut, folosește un parametru [FromHeader(Name = "X-Limba")] string? limba.
- Întoarce Hello! dacă limba == "en", altfel Salut!.
- În GET /produse, primește HttpResponse raspuns, setează raspuns.Headers["X-Total-Count"] și întoarce lista.
Soluția exercițiului
using Microsoft.AspNetCore.Mvc;
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("/salut", ([FromHeader(Name = "X-Limba")] string? limba) =>
limba == "en" ? "Hello!" : "Salut!");
app.MapGet("/produse", (HttpResponse raspuns) =>
{
raspuns.Headers["X-Total-Count"] = produse.Count.ToString();
return produse;
});
app.Run();
record Produs(int Id, string Nume, decimal Pret); 