CHAPITRE 6 : CREER UNE API REST

Nous construisons ici une API complete pour gerer des etudiants : lister, chercher, creer, modifier, supprimer.

1. Les principes REST

Une API REST expose des ressources identifiees par des URL, que l'on manipule avec les verbes HTTP.

Deux conventions utiles : l'URL designe une chose (un nom, au pluriel), pas une action. On ecrit /etudiants, jamais /getEtudiants : le verbe HTTP dit deja ce qu'on fait.

2. Le controleur

@RestController
@RequestMapping("/api/etudiants")
public class EtudiantController {

    private final EtudiantService service;

    public EtudiantController(EtudiantService service) {
        this.service = service;
    }

    @GetMapping
    public List<Etudiant> lister() {
        return service.listerTous();
    }

    @GetMapping("/{id}")
    public Etudiant consulter(@PathVariable Long id) {
        return service.trouverParId(id);
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Etudiant creer(@RequestBody Etudiant etudiant) {
        return service.enregistrer(etudiant);
    }

    @PutMapping("/{id}")
    public Etudiant modifier(@PathVariable Long id, @RequestBody Etudiant etudiant) {
        return service.modifier(id, etudiant);
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void supprimer(@PathVariable Long id) {
        service.supprimer(id);
    }
}

3. Les annotations de parametres

@GetMapping
public List<Etudiant> rechercher(
        @RequestParam(required = false) String filiere,
        @RequestParam(defaultValue = "0") int page) {
    return service.rechercher(filiere, page);
}

4. Les codes de statut

Renvoyer systematiquement 200, y compris en cas d'echec, est une faute classique : le client ne peut plus distinguer le succes de l'erreur.

5. Maitriser la reponse avec ResponseEntity

@GetMapping("/{id}")
public ResponseEntity<Etudiant> consulter(@PathVariable Long id) {

    return service.trouverParId(id)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
}

ResponseEntity permet de choisir le code, les en-tetes et le corps. A utiliser des que la reponse varie selon le cas.

6. Le DTO : ne pas exposer ses entites

Renvoyer directement une entite expose toute sa structure interne : y compris des champs sensibles comme un mot de passe. Un DTO (objet de transfert) ne contient que ce que l'exterieur doit voir.

public record EtudiantDTO(Long id, String nom, String matricule, double moyenne) { }

@GetMapping
public List<EtudiantDTO> lister() {
    return service.listerTous().stream()
                  .map(e -> new EtudiantDTO(e.getId(), e.getNom(),
                                            e.getMatricule(), e.getMoyenne()))
                  .toList();
}

7. Tester son API

curl http://localhost:8080/api/etudiants

curl -X POST http://localhost:8080/api/etudiants \
     -H "Content-Type: application/json" \
     -d '{"nom":"Awa Ngono","matricule":"19A123","moyenne":15.5}'

curl -X DELETE http://localhost:8080/api/etudiants/1

L'option -i affiche le code de statut : indispensable pour verifier que vous renvoyez bien 201 a la creation.

A retenir

• Une URL designe une ressource, le verbe HTTP dit l'action
• @PathVariable pour l'URL, @RequestParam pour la query, @RequestBody pour le JSON
• Choisissez le bon code : 201 a la creation, 204 a la suppression, 404 si absent
• N'exposez pas vos entites : passez par des DTO