Construiești un API care ține minte plantele din apartament și la câte zile trebuie udată fiecare. Orice program îl poate folosi prin HTTP: o aplicație de telefon, o pagină web sau curl. Așa arată două cereri:
terminal, cu aplicația pornită
$ curl -X POST localhost:8733/plante -H 'Content-Type: application/json' -d '{"nume":"Ficus","zile":7}'
{"id":1,"nume":"Ficus","zile":7}
$ curl localhost:8733/plante/9
{"eroare":"Planta 9 nu există"}
Prima cerere adaugă o plantă și primește înapoi numărul ei, cu codul 201. A doua cere o plantă care nu există și primește un mesaj clar, cu codul 404. Datele stau în memorie, ca să rămână lecția despre HTTP; baza de date vine în lecția despre Spring Data JPA.
să legi metode de adrese și verbe HTTP, cu @GetMapping, @PostMapping, @PutMapping și @DeleteMapping
să citești date din adresă și din corpul cererii
să alegi codul HTTP potrivit, cu ResponseEntity
să respingi datele greșite și să întorci erori clare
Pasul 2 din 5
Cerere cu cerere
Mai jos e controller-ul. Fiecare apăsare pe „Linia următoare” trimite o cerere nouă și arată ce metodă o primește, ce e în memorie și ce răspuns pleacă înapoi.
POST /plante, linia 29. Corpul cererii e {"nume":"Ficus","zile":7}. @RequestBody îl transformă din JSON în Planta, iar @Valid verifică regulile din record. Totul e în regulă, deci metoda rulează.
Linia 31. Serviciul îi dă plantei numărul 1 și o păstrează. ResponseEntity.status(201) trimite codul „Created”, cu planta nouă în corp.
Al doilea POST, linia 31. Același drum pentru Cactus, care primește numărul 2.
GET /plante, linia 19. Metoda întoarce o listă. Spring o transformă în JSON și pune codul 200, implicit pentru orice metodă care se termină normal.
GET /plante/9, linia 24.@PathVariable ia 9 din adresă. Serviciul nu-l găsește și aruncă NuExista. Clasa Erori din teorie prinde excepția și răspunde cu 404.
POST cu date greșite, linia 29. Numele e gol și zilele sunt 0. @Valid respinge planta înainte să intre în metodă: serviciul nici nu e chemat, iar clientul primește 400.
PUT /plante/2, linia 38. Cactusul primește 30 de zile în loc de 21. PUT înlocuiește planta întreagă, păstrând numărul din adresă.
DELETE /plante/1, linia 45. Ficusul e șters. noContent() trimite 204: totul a mers, dar nu e nimic de arătat.
Gata. În memorie a rămas doar cactusul. Un GET pe /plante ar întoarce acum [{"id":2,"nume":"Cactus","zile":30}].
Răspunsul 400 are în realitate și un câmp timestamp cu ora cererii; l-am scos ca să încapă.
Prezice ieșirea
După toate cererile de mai sus, trimiți GET /plante/1. Ce primești?
Răspuns: 404, „Planta 1 nu există”.
Ficusul a fost șters cu DELETE. gaseste(1) nu-l mai găsește, aruncă NuExista, iar Erori o transformă în 404.
Pasul 3 din 5
Cum e construit un API
Patru idei, cu fișierele reale din proiect. La final, trei greșeli pe care le vei face sigur o dată.
1
Controller-ul vorbește HTTP, serviciul decide
Controller-ul primește cererea, scoate datele din ea și alege codul răspunsului. Regulile stau în PlantaService, un bean primit prin constructor. De exemplu, căutarea:
Serviciul nu știe nimic despre HTTP: aruncă o excepție, iar cineva de deasupra decide că ea înseamnă 404. Așa poți folosi aceeași regulă și dintr-un test, și dintr-o comandă programată. Cum ajunge serviciul în constructor afli în lecția despre containerul Spring, din lista de la final.
2
Un verb HTTP, o adnotare
Verbele HTTP și adnotările Spring corespunzătoare
Cerere
Ce face aici
GET /plante
citește lista
GET /plante/2
citește o plantă
POST /plante
adaugă o plantă nouă
PUT /plante/2
înlocuiește planta 2
DELETE /plante/2
șterge planta 2
@RequestMapping("/plante") pe clasă dă începutul comun al adreselor. {id} din adresă ajunge în parametrul marcat cu @PathVariable, convertit în long. Corpul JSON ajunge în parametrul marcat cu @RequestBody.
3
Codul HTTP spune clientului ce s-a întâmplat
Codurile HTTP folosite în lecție
Cod
Când îl trimiți
200 OK
citire sau modificare reușită
201 Created
ai creat ceva nou
204 No Content
a mers, dar n-ai nimic de trimis
400 Bad Request
datele trimise sunt greșite
404 Not Found
nu există ce ai cerut
Dacă metoda întoarce direct un obiect, Spring pune 200. Când vrei alt cod, întorci un ResponseEntity: status(201).body(noua) sau noContent().build().
4
Validare și erori într-un singur loc
Planta.java
package ro.exemplu.plante;import jakarta.validation.constraints.*;record Planta( Long id,@NotBlank String nume,@Min(1) int zile) {}
Regulile stau chiar pe câmpuri: @NotBlank cere un nume cu măcar o literă, @Min(1) cere cel puțin o zi. Se aplică doar unde scrii @Valid, și au nevoie de starterul spring-boot-starter-validation.
package ro.exemplu.plante;class NuExista extends RuntimeException { NuExista(long id) {super("Planta " + id + " nu există"); }}
@RestControllerAdvice se aplică tuturor controller-elor. Când orice metodă aruncă NuExista, Spring cheamă lipsa, iar mesajul excepției ajunge în JSON.
Capcană: JSON trimis fără Content-Type
curl -d fără antet trimite datele ca formular. Spring nu știe să facă din formular un @RequestBody:
HTTP/1.1 415
{"timestamp":"2026-11-07T22:11:59.482+00:00","status":415,"error":"Unsupported Media Type","path":"/plante"}
Content-Type 'application/x-www-form-urlencoded;charset=UTF-8' is not supported
Repară adăugând antetul: -H 'Content-Type: application/json'. Ultimul rând e din jurnalul aplicației, nu din răspuns.
Capcană: reguli scrise, dar neaplicate
Ai pus @NotBlank și @Min(1) în record, dar ai uitat @Valid în controller. Datele greșite trec fără nicio problemă:
HTTP/1.1 201
{"id":1,"nume":"","zile":0}
Repară cu @Valid înaintea lui @RequestBody; aceeași cerere primește acum 400.
Capcană: text acolo unde aștepți număr
GET /plante/abc nu ajunge în metodă: abc nu se poate face long. Clientul primește 400, iar jurnalul spune de ce:
Resolved [org.springframework.web.method.annotation.MethodArgumentTypeMismatchException: Method parameter 'id': Failed to convert value of type 'java.lang.String' to required type 'long'; For input string: "abc"]
Nu e nimic de reparat în cod: 400 e răspunsul corect. Când depanezi, caută însă motivul în jurnal, nu în corpul răspunsului.
Pasul 4 din 5
Verifică-te
Cinci întrebări noi. După fiecare răspuns vezi imediat de ce e așa.
1 din 5 · Alege varianta
Ce adnotare pui pe parametrul care primește numărul din /plante/{id}?
Răspuns: @PathVariable.
@PathVariable citește o bucată din adresă. @RequestBody citește corpul cererii, iar @Valid doar cere verificarea regulilor.
2 din 5 · Prezice ieșirea
Aplicația abia a pornit, memoria e goală. Trimiți PUT /plante/5 cu {"nume":"Aloe","zile":14}. Ce cod primești?
Răspuns: 404.
Datele sunt valide, deci trec de @Valid. Dar schimba cheamă întâi gaseste(5), care aruncă NuExista, iar Erori răspunde cu 404.
3 din 5 · Alege varianta
Ce cod e potrivit pentru un DELETE reușit care nu trimite nimic înapoi?
Răspuns: 204.
204 No Content înseamnă „a mers, corpul e gol”. 201 e pentru ceva nou creat, iar 404 pentru ceva care nu există.
4 din 5 · Prezice ieșirea
Trimiți POST /plante cu {"nume":"Iederă","zile":-3}. Ce se întâmplă?
Răspuns: 400, fără apel la serviciu.
@Min(1) respinge -3. Verificarea se face înainte de corpul metodei, deci linia service.adauga(p) nu rulează.
5 din 5 · Alege varianta
De ce aruncă serviciul o excepție, în loc să întoarcă direct un 404?
Răspuns: ca serviciul să nu depindă de HTTP.
„Nu există” e o regulă a aplicației. Faptul că se traduce în 404 ține de web, așa că traducerea stă în @RestControllerAdvice.
Pasul 5 din 5
Ce ai învățat
Fiecare verb HTTP are adnotarea lui: @GetMapping, @PostMapping, @PutMapping, @DeleteMapping.
@PathVariable citește din adresă, @RequestBody din corpul JSON.
Un obiect întors direct înseamnă 200; pentru 201 sau 204 folosești ResponseEntity.
@Valid aplică regulile de pe câmpuri, iar @RestControllerAdvice traduce excepțiile în coduri HTTP.
Încearcă singur
Copiază cele cinci fișiere din lecție într-un proiect cu „Spring Web” și „Validation”, pornește-l și trimite cererile din pasul 2. Apoi adaugă GET /plante/de-udat?zi=14, care întoarce doar plantele cu cel mult 14 zile între udări; parametrul din ? îl citești cu @RequestParam int zi.