...
← Curs ASP.NET Core: toate lecțiile
Lecția 18 · HTTP

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ÎnLa ce folosește
Content-Typecerere și răspunsformatul corpului (application/json)
Authorizationcereredovada că ești autentificat (în modulul de securitate)
User-Agentcererece aplicație sau browser trimite cererea
Accept-Languagecererelimbile preferate de utilizator
Locationrăspunsadresa unei resurse create (la 201)
X-...oricareantete 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 /salut
GET /salut → 200 OK
Hello!
GET /salut → 200 OK
Salut!
GET /salut → 200 OK
Salut!
1
[FromHeader(Name = "X-Limba")] spune: valoarea parametrului vine din antetul X-Limba al cererii.
2
Name e necesar pentru că numele antetului (X-Limba) nu poate fi nume de variabilă C# (are cratimă).
3
Tipul este string?, deci antetul e opțional: când lipsește, limba este null și răspunsul e „Salut!”.
Comentariile de test cu antete

Î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-Count
GET /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 înCândExemple
cale sau querydescrie ce resursă vrei/produse/15, ?pagina=2
antetdescrie contextul cererii, același pentru multe cererilimba, 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.
Exercițiul tău

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.
Valoarea antetului de răspuns este text: produse.Count.ToString().

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);
Excelent! Continuă cu lecția următoare →
Program.csASP.NET Core
ConsolăSe încarcă...
Mediul de lucru se încarcă. Poți citi lecția între timp.
Rulează codul cu butonul de sus sau cu Ctrl + Enter / Cmd + Enter.
Parcursul tău Primul tău API cu ASP.NET Core Lecția 18 · Antete HTTP: citești și scrii headere
Progres 0% 0 din 22
Lecția curentă 18 / 20 Http