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"}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 /recenziiTomcat 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ția | Succes | Erori uzuale |
|---|---|---|
| GET /resurse | 200 cu lista (poate fi []) | rar: 400 pentru filtre greșite |
| GET /resurse/{id} | 200 cu resursa | 404 |
| POST /resurse | 201 + Location + resursa | 400 (date greșite) |
| PUT /resurse/{id} | 200 cu resursa | 404, 400 |
| PATCH /resurse/{id} | 200 cu resursa | 404, 400 |
| DELETE /resurse/{id} | 204 fără corp | 404 |
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.
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.
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).
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();
}
} 