
Lundi matin, Samuel ouvre un ticket au titre inquiétant :
Une demande s’est approuvée toute seule.
Vous remontez le fil avec Karim. Vendredi, il a collé le lien d’approbation de la demande d’Amina Diallo dans la messagerie de l’équipe, pour demander l’avis d’un collègue. La messagerie a aussitôt affiché un aperçu du lien : pour le construire, elle a envoyé une requêteGETà l’adresse… et approuvé la demande. Puis Karim, convaincu, a cliqué lui-même sur le lien. Hamac a approuvé la demande une seconde fois, et décompté deux fois les jours d’Amina.
Dans le même temps, Inès vous annonce que le branchement des pages web commence la semaine prochaine. Les pages Thymeleaf et leur JavaScript fonctionnent aujourd’hui sur des données simulées, et elles ont besoin de quatre opérations : consulter un solde, lister les demandes, déposer une demande, approuver ou refuser. L’API n’en propose que deux, et vous savez dans quel état.
L’incident de vendredi n’est pas un bug de la messagerie. Le protocole HTTP définitGETcomme un verbe sûr : une requêteGETsert à lire, et ne doit jamais modifier de données. Tous les outils du web s’appuient sur cette garantie. Les messageries ouvrent les liens pour en afficher un aperçu, les navigateurs préchargent les pages, les moteurs de recherche suivent tous les liens qu’ils trouvent. Aucun d’eux ne se méfie d’unGET.
En approuvant une demande sur un@GetMapping, le starter a rompu cette garantie. Et commeapprovene vérifie pas le statut de la demande, rien n’a empêché la seconde approbation. Deux défauts se sont combinés : un verbe mal choisi et une règle métier absente. Vous allez corriger les deux.
Les routes du starter décrivent des actions :/api/leave/balance,/api/leave/approve. Une API REST s’organise plutôt autour de ressources : les objets métier que le client manipule, désignés par des noms. Dans Hamac, il y en a deux : les salariés et les demandes de congés. Chaque ressource a une adresse, et le verbe HTTP indique ce que l’on veut en faire.
Besoin des pages web | Route du starter | Route du nouveau contrat |
Consulter le solde d’un salarié |
|
|
Lister les demandes, éventuellement par statut | — |
|
Consulter une demande | — |
|
Déposer une demande | — |
|
Approuver une demande |
|
|
Refuser une demande | — |
|
Remarquez la différence entre l’identifiant et le filtre. L’identifiant désigne une ressource précise : il fait partie du chemin (leave-requests/7), et Spring le lit avec@PathVariable. Le filtre restreint une liste : il passe dans la chaîne de requête (?status=PENDING), et Spring le lit avec@RequestParam. Ce découpage détermine aussi les réponses : une demande n° 999 qui n’existe pas mérite un404, alors qu’une liste filtrée sans résultat est simplement une liste vide.
Le contrat répartit ces routes entre deux contrôleurs, un par ressource :BalanceController, sous/api/employees, etLeaveRequestsController, sous/api/leave-requests. C’est la responsabilité unique appliquée aux contrôleurs.
Le solde est une ressource des salariés. PourquoiBalanceControllerrejoint-il le packageleaveet nonemployee?
Parce que les adresses et les packages ne répondent pas à la même question. L’adresse décrit ce que voit le client : un solde appartient à un salarié. Le package décrit qui travaille avec qui dans le code : le solde est calculé parLeaveService, avec les politiques de congés, qui sont toutes package-private dansleave. Placer le contrôleur ailleurs vous obligerait à rendre le servicepublic, uniquement pour respecter la forme de l’URL.
Lire un solde, lister ou consulter des demandes ne modifie rien : c’est le rôle deGET. Déposer une demande crée une nouvelle ressource : c’est le rôle dePOSTsur la collectionleave-requests.
L’approbation demande plus de réflexion. Elle modifie une demande existante, mais ce n’est pas une simple modification : elle déclenche une règle métier, met à jour le salarié et envoie une notification. Le contrat la représente donc comme la création d’une décision, avec unPOSTsur une sous-ressource :leave-requests/7/approval.
Pourquoi ne pas utiliserPATCH /api/leave-requests/7avec{ "status": "APPROVED" }?
Parce que ce contrat permettrait au client de choisir n’importe quel statut. Rien n’empêcherait d’envoyerAPPROVEDpour une demande que le solde ne couvre pas, ou de repasser une demande refusée en attente. Le statut d’une demande n’est pas une donnée que l’on modifie librement, c’est le résultat d’une décision encadrée par les règles RH. Une route dédiée à chaque décision garde ces règles du côté du serveur.
Le starter répond200à tout, y compris quand le salarié n’existe pas :getBalancerenvoie alors la chaîne"Employee not found". Pour savoir si la requête a réussi, le JavaScript des pages devrait donc lire le texte de la réponse et le comparer à des chaînes connues. Le jour où quelqu’un corrigera une faute de frappe dans ce message, les pages cesseront de détecter l’erreur.
Le code de statut est fait pour ça : c’est la partie de la réponse que tous les clients savent interpréter, sans connaître votre API. Le nouveau contrat en utilise cinq :
Statut | Signification | Dans Hamac |
| La requête a réussi, la réponse contient le résultat. | Un solde, une liste, une demande après décision |
| Une ressource a été créée. L’en-tête | Une demande déposée |
| Les données envoyées sont invalides. | Une date de fin antérieure à la date de début |
| La ressource désignée par l’adresse n’existe pas. | La demande n° 999 |
| La requête est valide, mais incompatible avec l’état actuel de la ressource. | Approuver une demande déjà traitée |
Le409correspond exactement à la seconde approbation de Karim. La demande existe et la requête est bien formée, mais la demande n’est plus en attente : la décision a déjà été prise. Pour renvoyer ce statut, le service doit d’abord connaître cette règle. C’est une règle métier que le starter avait oubliée, et Samuel vous a confirmé qu’une demande ne se traite qu’une fois.ApprovalResultreçoit donc une nouvelle valeur,NOT_PENDING, et leswitchexhaustif du contrôleur vous signalera, à la compilation, qu’il doit la traiter.
Si le solde ne couvre pas la demande, l’approbation aboutit à un refus. Pourquoi ne pas répondre par une erreur ?
Parce que la requête a bien été traitée. La règle RH prévoit qu’une demande non couverte par le solde est refusée, et ce refus est enregistré. Une réponse4xxsignifierait au contraire que le serveur n’a rien fait. L’API répond donc200, avec la demande à jour : son statutREFUSEDindique le résultat de la décision.
Les statuts métier sont définis par l’énumérationLeaveStatus:PENDING,APPROVEDetREFUSED. DansLeaveRequest, remplacez le typeStringdu champ et de ses accesseurs parLeaveStatus, et annotez le champ pour conserver les noms dans la base :
@Enumerated(EnumType.STRING)
private LeaveStatus status;Le paramètrestatusdu contrôleur utilise aussiLeaveStatus: Spring convertit par exemple?status=PENDINGen constante. Une valeur inconnue entraîne une réponse400, plutôt qu’une liste vide. Ces codes sont distincts des statuts HTTP comme200ou409.
Pour lister les demandes, le plus rapide serait de renvoyer directement les entités : une méthode de contrôleur qui renvoieList<LeaveRequest>, et Jackson les convertit en JSON. Le réflexe le plus risqué consiste justement à faire de vos entités le contrat de votre API.
Une entité décrit la façon dont les données sont stockées. Le contrat décrit ce que le client peut voir et envoyer. Si les deux se confondent, chaque évolution de la base devient une évolution de l’API. Renommez un champ de l’entité, et le JavaScript des pages cesse de fonctionner. Ajoutez un champ interne àEmployee, comme une note de la RH, et Jackson l’expose à tous les clients sans que personne ne l’ait décidé. Avec JPA, le risque est double : sérialiser une entité qui a des relations peut déclencher des requêtes imprévues, voire une erreur si la transaction est déjà terminée, ce qui est le cas depuis que vous avez désactivéopen-in-view.
Un DTO (Data Transfer Object) est un objet qui ne sert qu’à transporter des données entre l’API et ses clients. Il contient exactement les champs du contrat, ni plus ni moins. En Java, unrecordest fait pour ce rôle : ses valeurs sont fixées à la création, et Jackson sait le lire comme l’écrire. Au chapitre 4, vous avez vu qu’une entité JPA ne peut pas être un record ; un DTO, lui, peut et doit l’être. Hamac en a besoin de trois, dans le packageleave:
record BalanceDto(long employeeId, double balance) {
}record LeaveRequestDto(
long id,
long employeeId,
LocalDate startDate,
LocalDate endDate,
int workingDays,
LeaveStatus status) {
static LeaveRequestDto from(LeaveRequest request) {
return new LeaveRequestDto(
request.getId(),
request.getEmployeeId(),
request.getStartDate(),
request.getEndDate(),
request.getWorkingDays(),
request.getStatus());
}
}Jackson écrit lesLocalDateau format ISO, par exemple"2026-07-06", sans aucune configuration : c’est le format que le JavaScript des pages sait lire.
Le troisième,CreateLeaveRequestDto, décrit les données attendues pour déposer une demande. Il ne contient que trois champs : le salarié, la date de début et la date de fin. Le nombre de jours ouvrés est calculé par le service, et le statut initial est toujoursPENDING: le client ne peut décider ni de l’un ni de l’autre. Vous l’écrirez dans la section suivante, avec ses règles de validation.
La méthodefromcentralise la conversion d’une entité en DTO. Le service continue de manipuler des entités, et ce sont les contrôleurs qui les convertissent en DTO au moment de répondre : le contrat de l’API reste ainsi une affaire de la couche HTTP.
Au chapitre 4, vous avez découvert qu’une méthode dérivée peut renvoyer directement un record, une projection. Pourquoi ne pas faire renvoyerLeaveRequestDtopar le repository ?
Spring Data le permet : si les composants du record portent les mêmes noms que les champs de l’entité, une méthode commeList<LeaveRequestDto> findByStatus(String status)ne lit que ces colonnes et remplit le record. C’est très utile quand une liste n’affiche que trois colonnes d’une entité qui en compte trente. Ici, le DTO reprend tous les champs de la demande : la projection n’économiserait rien. Elle ferait en revanche dépendre le repository du contrat de l’API, et une évolution du JSON obligerait à modifier la couche d’accès aux données. Réservez les projections aux cas où elles allègent vraiment les requêtes, avec un record dédié plutôt qu’avec le DTO de l’API.
Les règles de validation se déclarent sur le DTO, avec les annotations de Jakarta Validation, la spécification standard de Java pour ce besoin. Elles ne sont pas incluses dans le starter web : ajoutez le starter correspondant aupom.xml, sans version, comme les autres.
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>Ce starter apporte Hibernate Validator, l’implémentation de référence de la spécification. Le piège est sournois : sans lui, les annotations de validation compilent… et ne sont jamais appliquées. Si vous oubliez cette dépendance, l’application démarre sans erreur, et une demande dont la date de fin précède la date de début est enregistrée sans que rien ne vous alerte.
record CreateLeaveRequestDto(
@NotNull @Positive Long employeeId,
@NotNull LocalDate startDate,
@NotNull LocalDate endDate) {
@JsonIgnore
@AssertTrue(message = "La date de fin doit être postérieure ou égale à la date de début.")
public boolean isDateRangeValid() {
return startDate == null || endDate == null || !endDate.isBefore(startDate);
}
}Un détail piège souvent les développeurs : l’identifiant du salarié est déclaréLong, et nonlong. Un type primitif ne peut pas valoirnull: si le client oublie le champ, il prend la valeur0, et@NotNullle considère comme rempli. Avec le type objet, un champ absent vautnull, et la validation échoue comme prévu, avec un message clair. LesLocalDatesont déjà des objets : un champ absent vautnull, et@NotNullle détecte.
La cohérence entre les deux dates ne peut pas s’exprimer avec une annotation sur un seul champ.@AssertTrue, placée sur une méthode dont le nom commence paris, ajoute une règle qui porte sur plusieurs champs : Hibernate Validator traite cette méthode comme une propriété,dateRangeValid, et exige qu’elle renvoietrue. Remarquez qu’elle renvoietruequand une date manque : ce cas est déjà signalé par@NotNull, inutile de produire deux erreurs pour le même oubli. Enfin,@JsonIgnorerappelle à Jackson, et à la documentation que vous générerez plus loin, que cette méthode n’est pas un champ du JSON.
Déclarer les règles ne suffit pas : il faut demander à Spring de les vérifier. C’est le rôle de@Valid, placée devant le paramètre qui reçoit le corps de la requête :
@PostMapping
ResponseEntity<LeaveRequestDto> create(@Valid @RequestBody CreateLeaveRequestDto dto) {
// …
}@RequestBodydemande à Jackson de convertir le JSON reçu enCreateLeaveRequestDto.@Validdemande ensuite de vérifier ses règles. Si l’une d’elles échoue, la méthode n’est même pas appelée : Spring lève uneMethodArgumentNotValidException, et la requête se termine par un400. Sans@Valid, les annotations du DTO sont tout simplement ignorées.
Toutes les vérifications n’ont pas leur place dans le DTO. La frontière est simple : le DTO vérifie ce qui se juge en lisant la requête seule, comme un champ manquant ou deux dates incohérentes. Tout ce qui demande de consulter les données relève du service : le salarié existe-t-il ? La demande est-elle encore en attente ? Le solde la couvre-t-il ?
Cette frontière protège vos règles métier. Si la vérification du solde se trouvait dans le DTO, une tâche planifiée qui appellerait le service directement y échapperait.
Toutes les vérifications n’ont pas leur place dans le DTO. La frontière est simple : le DTO vérifie ce qui se juge en lisant la requête seule, comme un champ manquant ou deux dates incohérentes. Tout ce qui demande de consulter les données relève du service : le salarié existe-t-il ? La demande est-elle encore en attente ? Le solde la couvre-t-il ?
Cette frontière protège vos règles métier. Si la vérification du solde se trouvait dans le DTO, une tâche planifiée qui appellerait le service directement y échapperait.
Un salarié inexistant pose une dernière question : quel statut renvoyer ? Pas404, car la ressource désignée par l’adresse, la collectionleave-requests, existe bien. Ce sont les données envoyées qui sont invalides : la réponse est un400.
Dans le contrôleur, le moyen le plus simple de signaler une erreur est de lever uneResponseStatusException, qui associe un statut HTTP à un message :
throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Cette demande n’existe pas.");Essayez-la surGET /api/leave-requests/999, sans autre configuration. Vous obtenez bien un404, mais avec un corps de ce type :
{
"timestamp": "2026-05-18T09:12:44.512Z",
"status": 404,
"error": "Not Found",
"path": "/api/leave-requests/999"
}C’est la réponse d’erreur générique de Spring Boot. Votre message a disparu : par défaut, Spring Boot ne l’inclut pas, par prudence. Et les erreurs de validation arrivent sous la même forme, sans dire quel champ pose problème. Le JavaScript des pages ne peut rien en tirer.
La RFC 9457 définit un format standard pour les erreurs d’une API HTTP, appelé Problem Details. Spring le représente par la classeProblemDetail, et Spring Boot sait l’appliquer à toutes les erreurs gérées par Spring MVC. Activez-le dansapplication.properties:
spring.mvc.problemdetails.enabled=trueLa même requête renvoie désormais :
{
"type": "about:blank",
"title": "Not Found",
"status": 404,
"detail": "Cette demande n’existe pas.",
"instance": "/api/leave-requests/999"
}Le message de votre exception est maintenant dansdetail. Le même format s’applique aux autres erreurs que Spring MVC sait reconnaître : un JSON mal formé, un identifiant qui n’est pas un nombre, et les erreurs de validation. Pour ces dernières, en revanche, le résultat est décevant :
{
"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "Invalid request content.",
"instance": "/api/leave-requests"
}Le client sait que sa requête est invalide, mais pas pourquoi.
La propriété que vous venez d’activer enregistre un gestionnaire d’exceptions fourni par Spring Boot, une sous-classe deResponseEntityExceptionHandler. Pour enrichir ses réponses, vous allez écrire la vôtre, dans le packageweb:
@RestControllerAdvice
class ApiExceptionHandler extends ResponseEntityExceptionHandler {
private static final Logger log = LoggerFactory.getLogger(ApiExceptionHandler.class);
@Override
protected ResponseEntity<Object> handleMethodArgumentNotValid(
MethodArgumentNotValidException ex, HttpHeaders headers,
HttpStatusCode status, WebRequest request) {
var errors = new LinkedHashMap<String, String>();
ex.getBindingResult().getFieldErrors()
.forEach(error -> errors.put(error.getField(), error.getDefaultMessage()));
var problem = ex.getBody();
problem.setDetail("Les données envoyées sont invalides.");
problem.setProperty("errors", errors);
return handleExceptionInternal(ex, problem, headers, status, request);
}
@ExceptionHandler(Exception.class)
ProblemDetail handleUnexpected(Exception ex) {
log.error("Unexpected error", ex);
return ProblemDetail.forStatusAndDetail(
HttpStatus.INTERNAL_SERVER_ERROR, "Une erreur inattendue s’est produite.");
}
}@RestControllerAdvicedéclare un bean qui intercepte les exceptions levées par tous les contrôleurs de l’application. En héritant deResponseEntityExceptionHandler, votre classe reprend tout le travail du gestionnaire de Spring Boot, et Spring Boot n’enregistre plus le sien : il ne le crée que si vous n’en fournissez pas. Vous ne redéfinissez que ce que vous voulez changer.
La première méthode ajoute à la réponse une propriétéerrors, qui associe chaque champ invalide à son message. La seconde traite toutes les exceptions que personne n’a prévues : elle enregistre le détail dans le journal de l’application et renvoie au client un500générique, au même format que les autres erreurs. Une exception plus précise, commeResponseStatusExceptionouMethodArgumentNotValidException, reste traitée par la méthode qui lui correspond : Spring choisit toujours le gestionnaire le plus spécifique.
Voici la réponse obtenue pour une demande dont la date de fin précède la date de début :
{
"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "Les données envoyées sont invalides.",
"instance": "/api/leave-requests",
"errors": {
"dateRangeValid": "La date de fin doit être postérieure ou égale à la date de début."
}
}Le JavaScript des pages pourra afficher ce message dans le formulaire, sans rien deviner. Les pages n’ont plus qu’un seul format d’erreur à traiter, quelle que soit sa cause.
Un contrat ne sert que s’il est connu de ceux qui l’utilisent. OpenAPI est un format standard qui décrit une API : ses routes, ses paramètres, ses DTO et ses réponses possibles. Spring Boot ne le génère pas lui-même : la bibliothèque de référence pour cela est springdoc-openapi. Elle ne fait pas partie des dépendances gérées par Spring Boot : il faut donc indiquer sa version. La branche 3.x est celle qui correspond à Spring Boot 4.
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>3.0.0</version>
</dependency>Relancez l’application. Deux adresses sont apparues :
http://localhost:8080/v3/api-docsrenvoie la description OpenAPI au format JSON. C’est ce document que vous transmettrez à l’équipe qui branche les pages web ;
http://localhost:8080/swagger-ui.htmlouvre Swagger UI, une page qui présente chaque route et permet de l’appeler directement depuis le navigateur, avec le bouton Try it out.
Springdoc construit cette description en lisant vos contrôleurs : les routes, les paramètres, les types de retour et les annotations de validation de vos DTO. C’est une raison supplémentaire de déclarer précisémentResponseEntity<LeaveRequestDto>plutôt qu’unObjectcomme le faisait le starter : unObjectn’apprend rien au lecteur de la documentation.
Pour rejouer l’incident de vendredi, deux commandes suffisent. L’option-iaffiche le statut et les en-têtes de la réponse :
curl -i -X POST http://localhost:8080/api/leave-requests/7/approval
curl -i -X POST http://localhost:8080/api/leave-requests/7/approvalLa première répond200, la seconde409. Pour déposer une demande, il faut envoyer un corps JSON et préciser son format :
curl -i -X POST http://localhost:8080/api/leave-requests \
-H "Content-Type: application/json" \
-d '{"employeeId": 4, "startDate": "2026-07-06", "endDate": "2026-07-10"}'La réponse201contient un en-têteLocation: http://localhost:8080/api/leave-requests/12: c’est l’adresse de la demande créée. Inversez les deux dates pour obtenir le400et son message. Si vous préférez une interface graphique, Swagger UI permet les mêmes essais.
Mettez donc à jour les tests existants pour qu’ils utilisent les nouvelles routes, puis ajoutez des tests pour les nouveaux comportements du contrat : les statuts d’erreur, la validation et l’interdiction de traiter deux fois une demande.
Un échec devrait toutefois vous surprendre. Deux tests deLeaveApprovalTestsapprouvent la demande n° 1 : celui du starter, et celui de la notification que vous avez ajouté au chapitre 4. Avec la nouvelle règle, celui qui s’exécute en second reçoit un409. La cause n’est pas dans le code de l’application, mais dans les tests : Spring garde le même contexte, et donc la même base H2, pour tous les tests de la classe. La première approbation est toujours là quand la seconde arrive. Vos tests dépendaient de leur ordre d’exécution, et la double approbation, justement, les rendait invisibles.
La correction tient en une annotation :@Transactionalsur la classe de test. Chaque test s’exécute alors dans une transaction que Spring annule à la fin, et le suivant retrouve les données dedata.sql. Cela fonctionne parce queMockMvcTestertraite la requête dans le même fil d’exécution que le test : la transaction du service rejoint celle du test, et l’annulation porte sur les deux.

Inès veut que le contrat soit prêt lundi, quand commencera le branchement des pages web. Samuel, lui, attend une seule chose : que l’incident de vendredi ne puisse plus se reproduire.
Créez l’énumérationLeaveStatusavec les trois statuts. DansLeaveRequest, utilisez-la pour le champstatus, ses accesseurs et son mapping JPA avec@Enumerated(EnumType.STRING). Utilisez aussi ce type dans le service, le repository et les DTO.
DansLeaveService, interdisez d’approuver une demande qui n’est plus en attente, puis ajoutez les méthodesgetRequests,getRequest,createetrefuse. Pourcreate, comptez les jours ouvrés du lundi au vendredi, sans tenir compte des jours fériés.
Ajoutezspring-boot-starter-validation, puis créez les trois DTO, avec les règles de validation deCreateLeaveRequestDto.
RemplacezLeaveControllerparBalanceControlleretLeaveRequestsController, qui exposent les six routes du nouveau contrat avec les statuts adaptés.
Activez ProblemDetail, puis écrivezApiExceptionHandlerpour compléter les erreurs de validation et traiter les erreurs inattendues.
Ajoutez springdoc-openapi, ouvrez Swagger UI et rejouez le scénario de l’incident avec curl : deux approbations successives de la même demande.
Mettez à jour les tests existants, rendez-les indépendants avec@Transactional, puis ajoutez au moins un test pour la double approbation et un test pour la validation des dates.
Point de contrôle : les six routes répondent avec les statuts du contrat. Une seconde approbation de la même demande renvoie409. Toutes les erreurs arrivent au format ProblemDetail. Aucune méthode de contrôleur ne renvoie d’entité. Swagger UI présente les six routes../mvnw testse termine parBUILD SUCCESS. Enregistrez votre travail avec Git.
Une API REST s’organise autour de ressources désignées par des noms. Le verbe HTTP indique ce que l’on veut en faire, et unGETne modifie jamais de données.
Une décision encadrée par des règles métier se représente par une route dédiée, plutôt que par une modification libre du statut.
Les codes de statut indiquent le résultat de la requête à tous les clients :200,201,400,404ou409selon le cas.
Les DTO, écrits enrecord, séparent le contrat de l’API du schéma de la base, et empêchent le client de remplir des champs qu’il ne doit pas contrôler. Ils valident ce qui se juge en lisant la requête, avec Jakarta Validation et@Valid; le service vérifie ce qui demande de consulter les données.
ProblemDetail donne un format unique à toutes les erreurs, et un@RestControllerAdvicepermet de l’enrichir. Springdoc, Swagger UI et des tests d’API indépendants documentent et protègent le contrat.
Hamac dispose maintenant d’un contrat d’API clair, documenté et testé, et l’incident de vendredi ne peut plus se reproduire. Dans le dernier chapitre, vous allez brancher les pages Thymeleaf sur ce contrat, ajouter enfin la politique des stages et documenter l’application pour la prochaine personne qui la reprendra.