...
← Curs Spring Boot și REST API: toate lecțiile
Lecția 13 · Răspunsuri

Coduri de status corecte: 201, 204 și @ResponseStatus

Un API bun spune exact ce s-a întâmplat. Când creezi ceva, răspunsul corect este 201 Created, cu adresa resursei noi în antetul Location. Când ștergi, 204 No Content. Înveți ResponseEntity.created, noContent și scurtătura @ResponseStatus.

201 Created și antetul Location

După un POST reușit, clientul vrea să știe două lucruri: că resursa a fost creată (nu doar „ok”) și unde o găsește. Codul 201 spune primul lucru, iar antetul Location pe al doilea.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import java.net.URI;
import java.util.*;

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

record Client(long id, String nume) { }

@RestController
@RequestMapping("/clienti")
class ClientController {
    private final List<Client> clienti = new ArrayList<>();

    @PostMapping
    ResponseEntity<Client> creeaza(@RequestBody Client primit) {
        Client client = new Client(clienti.size() + 1, primit.nume());
        clienti.add(client);
        return ResponseEntity.created(URI.create("/clienti/" + client.id())).body(client);
    }
}

// > POST /clienti {"nume": "Ana"}
// > POST /clienti {"nume": "Mihai"}
Tomcat started on port 8080 (http)
Started Application
POST /clienti → 201
Location: /clienti/1
{"id":1,"nume":"Ana"}
POST /clienti → 201
Location: /clienti/2
{"id":2,"nume":"Mihai"}
1
URI.create("/clienti/" + client.id()) construiește adresa resursei noi (java.net.URI).
2
ResponseEntity.created(uri) pune codul 201 și antetul Location cu acea adresă.
3
.body(client) adaugă resursa creată în corp, ca clientul să vadă id-ul primit.
Antetele în laborator

Laboratorul afișează antetele doar când exercițiul le cere. În lecția aceasta exercițiul cere antetul Location (setarea lab.showHeaders), așa că îl vezi sub linia de status, la toate cererile care îl au. În Postman, antetele sunt în tab-ul Headers al răspunsului.

204 No Content și @ResponseStatus

După o ștergere nu ai ce trimite înapoi. Codul potrivit este 204 No Content: „gata, și nu am nimic de spus”. Îl construiești cu ResponseEntity.noContent().build(), cu tipul ResponseEntity<Void> (Void = fără corp).

Dacă metoda întoarce mereu același cod, nu ai nevoie de ResponseEntity: pui @ResponseStatus(HttpStatus.CREATED) pe metodă și întorci obiectul direct. Diferența: @ResponseStatus nu poate adăuga antetul Location.

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import java.net.URI;
import java.util.*;

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

record Recenzie(int nota, String text) { }

@RestController
class RecenzieController {
    private final List<Recenzie> recenzii = new ArrayList<>();

    @PostMapping("/recenzii")
    @ResponseStatus(HttpStatus.CREATED)
    Recenzie adauga(@RequestBody Recenzie recenzie) {
        recenzii.add(recenzie);
        return recenzie;
    }

    @DeleteMapping("/recenzii")
    ResponseEntity<Void> stergeToate() {
        recenzii.clear();
        return ResponseEntity.noContent().build();
    }

    @GetMapping("/recenzii")
    List<Recenzie> toate() {
        return recenzii;
    }
}

// > POST /recenzii {"nota": 5, "text": "Foarte bun"}
// > DELETE /recenzii
// > GET /recenzii
Tomcat started on port 8080 (http)
Started Application
POST /recenzii → 201
{"nota":5,"text":"Foarte bun"}
DELETE /recenzii → 204
GET /recenzii → 200
[]

Ce cod pentru ce operație

OperațiaSuccesErori uzuale
GET /resurse200 cu lista (poate fi [])rar: 400 pentru filtre greșite
GET /resurse/{id}200 cu resursa404
POST /resurse201 + Location + resursa400 (date greșite)
PUT /resurse/{id}200 cu resursa404, 400
PATCH /resurse/{id}200 cu resursa404, 400
DELETE /resurse/{id}204 fără corp404

Tabelul este convenția REST folosită de majoritatea API-urilor publice (Stripe, GitHub). Când vei integra servicii externe, te vei baza pe aceste coduri ca să știi dacă o operație a reușit.

De ce contează codurile

  • Aplicația client decide după cod ce afișează: 201 → „Comanda a fost plasată”, 404 → „Produsul nu mai există”.
  • Monitorizarea (Grafana, Datadog) numără răspunsurile pe familii: multe 5xx înseamnă o problemă pe server, multe 4xx, o problemă la clienți.
  • Retry-ul automat al clienților folosește codul ca să decidă dacă reîncearcă: un 503 se reîncearcă, un 400 nu.
Corpul gol la 204

Un răspuns 204 nu are voie să aibă corp. De aceea laboratorul arată doar linia DELETE ... → 204. Dacă vrei să trimiți ceva înapoi după ștergere, folosește 200 cu corp.

Greșeli frecvente

  • 200 pentru creare: funcționează, dar clientul nu află adresa resursei noi; folosește 201 cu Location.
  • **created() fără body(...)**: răspunsul nu conține resursa nouă; adaugă corpul ca clientul să vadă id-ul.
  • **Location greșit**: trebuie să fie adresa la care GET găsește resursa (/sarcini/3), nu adresa colecției.
  • **Uiți build()** după noContent() (la fel ca la notFound()).

Pe scurt

  • Creare: ResponseEntity.created(URI.create("/x/" + id)).body(obiect) → 201 + Location.
  • Ștergere: ResponseEntity.noContent().build() cu tipul ResponseEntity<Void> → 204.
  • @ResponseStatus(HttpStatus.CREATED) pe metodă: un cod fix, fără ResponseEntity (dar fără Location).
  • Convenția: GET 200, POST 201, PUT/PATCH 200, DELETE 204, resursă lipsă 404.
Exercițiul tău

API-ul de sarcini răspunde acum cu 200 la toate. Corectează codurile: POST /sarcini răspunde cu 201, antetul Location: /sarcini/{id} și sarcina creată în corp, iar DELETE /sarcini/{id} răspunde cu 204 fără corp. Laboratorul trimite un POST și DELETE /sarcini/1, și afișează antetul Location.

  • Schimbă metoda creeaza să întoarcă ResponseEntity<Sarcina> cu ResponseEntity.created(URI.create("/sarcini/" + sarcina.id())).body(sarcina).
  • Schimbă metoda sterge să întoarcă ResponseEntity<Void> cu ResponseEntity.noContent().build().
  • Păstrează logica existentă (contorul, lista, removeIf).
URI vine din java.net.URI, deja importat. Nu uita build() după noContent().

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.HttpStatus;
import org.springframework.http.ResponseEntity;
import java.net.URI;
import java.util.*;

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

record Sarcina(long id, String titlu) { }

@RestController
@RequestMapping("/sarcini")
class SarcinaController {
    private final List<Sarcina> sarcini = new ArrayList<>();
    private long ultimulId = 0;

    @PostMapping
    ResponseEntity<Sarcina> creeaza(@RequestBody Sarcina primita) {
        ultimulId++;
        Sarcina sarcina = new Sarcina(ultimulId, primita.titlu());
        sarcini.add(sarcina);
        return ResponseEntity.created(URI.create("/sarcini/" + sarcina.id())).body(sarcina);
    }

    @DeleteMapping("/{id}")
    ResponseEntity<Void> sterge(@PathVariable long id) {
        sarcini.removeIf(s -> s.id() == id);
        return ResponseEntity.noContent().build();
    }
}
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 13 · Coduri de status corecte: 201, 204 și @ResponseStatus
Progres 0% 0 din 20
Lecția curentă 13 / 18 Răspunsuri