Module 02 — API REST (Spring MVC) : parler HTTP proprement

Objectif : construire des endpoints compréhensibles, testables, et cohérents (codes HTTP, validation, erreurs).

---

1) REST : à quoi ça sert ?

REST = un style d’API basé sur :

• des ressources (chiens, races, concours…)
• des verbes HTTP (GET, POST, PUT, DELETE)
• des codes HTTP qui racontent ce qui s’est passé

---

2) Verbes HTTP : l’intention

Verbe	Intention	Exemple
GET	lire	GET /api/chiens/10
POST	créer	POST /api/chiens
PUT	remplacer	PUT /api/chiens/10
DELETE	supprimer	DELETE /api/chiens/10

---

3) Codes HTTP : grammaire de l’API

Code	Sens	Quand l’utiliser
200 OK	succès	lecture / update
201 Created	créé	création (POST)
400 Bad Request	entrée invalide	validation, JSON incorrect
404 Not Found	inexistant	id non trouvé
409 Conflict	conflit métier	doublon, état interdit
500 Server Error	bug	exception non gérée

En entreprise, une API se juge aussi sur ses codes HTTP.

---

4) Le controller REST : rôle limité

Un controller doit :

1. recevoir une requête (JSON)
2. déclencher validation (@Valid)
3. déléguer au service concernée
4. renvoyer une réponse (DTO + code HTTP)

Il ne doit pas :

• Contenir des règles métier car ce n’est pas son rôle.
• Appeler directement la base de données en dur !
• Renvoyer une entity JPA au front-end.

---

5) Annotations indispensables que nous allons utiliser

• @RestController : Retourne du JSON automatiquement.
• @RequestMapping("/api/...") : Préfixe commun.
• @GetMapping, @PostMapping : Mappe les routes.
• @RequestBody : Corps JSON pour les objets Java.
• @PathVariable : Valeur passée dans l’URL.
• @RequestParam : Paramètre dans la query string.

---

6) Exemple complet (pattern standard)

@RestController
@RequestMapping("/api/races")
class RaceController {

  private final RaceService service;

  RaceController(RaceService service)
  {
	this.service = service;
  }

  @GetMapping
  List<RaceDto> list()
  {
	return service.list();
  }

  @PostMapping
  ResponseEntity<RaceDto> create(@Valid @RequestBody RaceCreateDto dto)
  {
    RaceDto created = service.create(dto);
    return ResponseEntity.status(201).body(created);
  }
}

---

7) Tester une API dès le début avec curl

curl -X POST http://localhost:8080/api/races   -H "Content-Type: application/json"   -d '{"code":"BA","nom":"Berger Australien"}'

Nous utiliserons plutôt Swagger ou Postman.

---

8) UML : diagramme de séquence Créer une race

Schéma logique :

Client -> RaceController -> RaceService -> RaceRepository -> DB

UML vous aide à :

• placer la règle au bon endroit (service)
• éviter d’éparpiller la logique

---

9) Questions

1. Quelle différence entre 400 et 409 ? Donnez un exemple concret.
2. Pourquoi GET /api/creerChien est un mauvais choix ?
3. Dans l’application Wouaf Wouaf, repérez un endpoint qui renvoie une Entity et proposez comment le transformer en DTO.