...
← Curs Spring Boot și REST API: toate lecțiile
Lecția 14 · HTTP

Antete HTTP: citire și scriere

Pe lângă cale și corp, fiecare cerere și fiecare răspuns poartă antete: limba preferată a utilizatorului, aplicația care trimite cererea, token-ul de autentificare. În lecția aceasta citești antete cu @RequestHeader și le scrii în răspuns cu ResponseEntity.

Ce sunt antetele

Antetele sunt perechi Nume: valoare care însoțesc cererea sau răspunsul. Ele nu sunt datele propriu-zise, ci informații despre cerere: cine o trimite, ce format acceptă, cine este utilizatorul. Numele antetelor nu țin cont de literele mari (accept-language = Accept-Language).

AntetÎnLa ce folosește
Accept-Languagecererelimba preferată a utilizatorului (ro, en)
User-Agentcerereaplicația care trimite cererea (browser, Postman, aplicația mobilă)
Authorizationcereredovada identității: Bearer <token>
X-Request-Idcerereun id unic al cererii, ca să o găsești în jurnale
Content-Typeambeleformatul corpului (application/json)
Locationrăspunsadresa resursei create (lecția 13)
Cache-Controlrăspunscât timp poate fi păstrat răspunsul în cache

Antetele care încep cu X- sunt, prin convenție, antete proprii ale unei aplicații.

Citirea cu @RequestHeader

@RequestHeader("Nume") pe un parametru pune valoarea antetului în el. Ca la @RequestParam: este obligatoriu implicit, iar cu required = false primești null când lipsește. În laborator, un antet se adaugă sub cerere, pe un rând // > Nume: valoare (cu cel puțin două spații după >):

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

@RestController
class DiagnosticController {
    @GetMapping("/client")
    String client(@RequestHeader("User-Agent") String agent,
                  @RequestHeader(value = "X-Request-Id", required = false) String idCerere) {
        String text = "Client: " + agent;
        if (idCerere != null) {
            text = text + " (cererea " + idCerere + ")";
        }
        return text;
    }
}

// > GET /client
// >   User-Agent: Postman
// >   X-Request-Id: r-1042
// > GET /client
// >   User-Agent: curl/8.4
Tomcat started on port 8080 (http)
Started Application
GET /client → 200
Client: Postman (cererea r-1042)
GET /client → 200
Client: curl/8.4

A doua cerere nu are X-Request-Id, deci parametrul este null și textul nu îl mai include.

Antet lipsă: 400

Un antet obligatoriu care lipsește dă 400 Bad Request, iar metoda nu rulează. Cu setarea care include mesajul în răspuns, vezi exact ce lipsește:

/* application.properties
server.error.include-message=always
*/

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

@RestController
class ContController {
    @GetMapping("/cont")
    String cont(@RequestHeader("Authorization") String autorizare) {
        return "Am primit: " + autorizare;
    }
}

// > GET /cont
// >   Authorization: Bearer t-ana
// > GET /cont
Tomcat started on port 8080 (http)
Started Application
GET /cont → 200
Am primit: Bearer t-ana
GET /cont → 400
{"status":400,"error":"Bad Request","message":"Required request header 'Authorization' for method parameter type String is not present","path":"/cont"}
Antete cu valoare implicită

Pentru antete care pot lipsi, dar au o valoare firească, folosește defaultValue: @RequestHeader(value = "Accept-Language", defaultValue = "ro") String limba. Când clientul nu trimite antetul, primești ro.

Scrierea antetelor în răspuns

Ca să pui antete în răspuns, întorci un ResponseEntity construit pas cu pas: ResponseEntity.ok() (fără argument), apoi câte un .header(nume, valoare) pentru fiecare antet, iar la final .body(...). Laboratorul arată antetele cerute de exemplu sub linia de status.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;
import org.springframework.http.ResponseEntity;

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

record Produs(String nume, double pret) { }

@RestController
class ProdusController {
    @GetMapping("/produse/promo")
    ResponseEntity<Produs> promo() {
        return ResponseEntity.ok()
            .header("X-Limba", "ro")
            .header("X-Promo-Expira", "2026-03-31")
            .header("Cache-Control", "max-age=60")
            .body(new Produs("Mouse Silent", 79.0));
    }
}

// > GET /produse/promo
Tomcat started on port 8080 (http)
Started Application
GET /produse/promo → 200
X-Limba: ro
{"nume":"Mouse Silent","pret":79.0}

Răspunsul are trei antete, dar laboratorul afișează doar antetele cerute de exercițiul lecției, aici X-Limba. Pe celelalte (X-Promo-Expira, Cache-Control) le-ai vedea în Postman, în tab-ul Headers, sau cu curl -i.

Exemple reale

  • Site-uri în mai multe limbi citesc Accept-Language și răspund cu texte în limba utilizatorului.
  • API-urile cu autentificare citesc Authorization la fiecare cerere (în modulul de securitate faci asta într-un filtru, pentru toate rutele deodată).
  • Paginarea trimite des numărul total de rezultate într-un antet, de exemplu X-Total-Count: 245.
  • Echipele de suport caută după X-Request-Id în jurnale când un client raportează o eroare.

Greșeli frecvente

  • Antet obligatoriu care de fapt poate lipsi: clienții primesc 400. Folosește required = false sau defaultValue.
  • Date în antete în loc de corp: antetele sunt pentru informații scurte despre cerere; datele (produsul, comanda) stau în corp.
  • **Uiți .body(...)** după .header(...): fără el nu ai un ResponseEntity complet.
  • **Compari limba cu ==**: pentru texte folosește equals, ca în orice cod Java.

Pe scurt

  • Antetele sunt perechi Nume: valoare cu informații despre cerere sau răspuns.
  • @RequestHeader("Nume") citește un antet; lipsa unui antet obligatoriu dă 400.
  • required = false (primești null) sau defaultValue = "..." pentru antete opționale.
  • ResponseEntity.ok().header("Nume", "valoare").body(corp) scrie antete în răspuns.
Exercițiul tău

Fă salutul să vorbească limba utilizatorului. GET /salut citește antetul Accept-Language (implicit ro) și răspunde cu Hello! pentru en, altfel cu Salut!. Răspunsul are și antetul X-Limba cu limba citită. Laboratorul trimite o cerere fără antet și una cu Accept-Language: en, și afișează antetul X-Limba.

  • Primește limba cu @RequestHeader(value = "Accept-Language", defaultValue = "ro") String limba.
  • Alege textul: Hello! dacă limba.equals("en"), altfel Salut!.
  • Întoarce ResponseEntity<String> cu ResponseEntity.ok().header("X-Limba", limba).body(text).
Schimbă tipul întors al metodei în ResponseEntity<String>; operatorul ? : alege elegant între două texte.

Soluția exercițiului

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;
import org.springframework.http.ResponseEntity;

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

@RestController
class SalutController {
    @GetMapping("/salut")
    ResponseEntity<String> salut(@RequestHeader(value = "Accept-Language", defaultValue = "ro") String limba) {
        String text = limba.equals("en") ? "Hello!" : "Salut!";
        return ResponseEntity.ok()
            .header("X-Limba", limba)
            .body(text);
    }
}
Excelent! Continuă cu lecția următoare →
Application.javaSpring Boot
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 Spring Boot Lecția 14 · Antete HTTP: citire și scriere
Progres 0% 0 din 20
Lecția curentă 14 / 18 Http