MyCodeSchool

Pasul 1 din 5

Spring Boot

Pasul 1 din 5 · Ce construiești

  • Spring Boot
  • Mediu
  • 14 minute

Primul API REST cu Spring Boot

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.

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.

PlantaController.java
package ro.exemplu.plante;import jakarta.validation.Valid;import java.util.List;import org.springframework.http.ResponseEntity;import org.springframework.web.bind.annotation.*;@RestController@RequestMapping("/plante")class PlantaController {    private final PlantaService service;    PlantaController(PlantaService service) {        this.service = service;    }    @GetMapping    List<Planta> toate() {        return service.toate();    }    @GetMapping("/{id}")    Planta una(@PathVariable long id) {        return service.gaseste(id);    }    @PostMapping    ResponseEntity<Planta> adauga(            @Valid @RequestBody Planta p) {        Planta noua = service.adauga(p);        return ResponseEntity.status(201)                .body(noua);    }    @PutMapping("/{id}")    Planta schimba(@PathVariable long id,            @Valid @RequestBody Planta p) {        return service.schimba(id, p);    }    @DeleteMapping("/{id}")    ResponseEntity<Void> sterge(            @PathVariable long id) {        service.sterge(id);        return ResponseEntity.noContent()                .build();    }}

Plantele din memorie

Răspunsul HTTP


      

  1. 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ă.
  2. Linia 31. Serviciul îi dă plantei numărul 1 și o păstrează. ResponseEntity.status(201) trimite codul „Created”, cu planta nouă în corp.
  3. Al doilea POST, linia 31. Același drum pentru Cactus, care primește numărul 2.
  4. 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.
  5. 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.
  6. 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.
  7. 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ă.
  8. DELETE /plante/1, linia 45. Ficusul e șters. noContent() trimite 204: totul a mers, dar nu e nimic de arătat.
  9. 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ă.

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:

PlantaService.java, fragment
Planta gaseste(long id) {    Planta p = plante.get(id);    if (p == null) {        throw new NuExista(id);    }    return p;}

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.

Un verb HTTP, o adnotare

Verbele HTTP și adnotările Spring corespunzătoare
CerereCe face aici
GET /plantecitește lista
GET /plante/2citește o plantă
POST /planteadaugă 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.

Codul HTTP spune clientului ce s-a întâmplat

Codurile HTTP folosite în lecție
CodCând îl trimiți
200 OKcitire sau modificare reușită
201 Createdai creat ceva nou
204 No Contenta mers, dar n-ai nimic de trimis
400 Bad Requestdatele trimise sunt greșite
404 Not Foundnu 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().

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.

Erori.java
package ro.exemplu.plante;import java.util.Map;import org.springframework.http.ResponseEntity;import org.springframework.web.bind.annotation.*;@RestControllerAdviceclass Erori {    @ExceptionHandler(NuExista.class)    ResponseEntity<Map<String, String>> lipsa(            NuExista e) {        return ResponseEntity.status(404)                .body(Map.of("eroare", e.getMessage()));    }}
NuExista.java
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

Î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.

Continuă cu