Connectez les pages web fournies et documentez votre application

Au chapitre précédent, vous avez livré à Inès un contrat d’API clair, documenté et testé. Mais pour Samuel, rien n’a changé : la page qu’il utilise affiche toujours des données simulées. Il voit des demandes qui n’existent pas, et un solde qui n’est pas le sien.

Inès vous transmet la suite. L’équipe a terminé la réécriture des pages web, mais elle est partie sur un autre projet sans les brancher.

Tout est prêt côté interface, il ne manque que les appels à l’API.

Samuel veut faire tester la page par Karim vendredi. Il a une autre échéance en tête : Zoé Mendes, la première stagiaire de l’entreprise, arrive lundi prochain, et son solde doit s’afficher dès son premier jour.

Inès ajoute une dernière demande. Tomás Herrera rejoindra l’équipe le mois prochain, et c’est lui qui maintiendra Hamac.

Je veux qu’il puisse lancer l’application sans m’appeler. Toi, tu n’as pas eu cette chance. 

Repérez ce que les pages attendent de l’API

Les pages de Hamac sont servies par l’application Spring Boot elle-même. Au chapitre 3, vous avez vu quePageControllerrenvoie le templatesrc/main/resources/templates/leave-requests.html. Ce template ne contient que la structure de la page : le tableau, le filtre, le formulaire et le sélecteur de langue. Les données sont chargées ensuite, dans le navigateur, par le JavaScript rangé danssrc/main/resources/static/js. Vous y trouvez trois fichiers :

  • app.js, qui remplit le tableau, gère le formulaire, les boutons et la bascule de langue ;

  • leave-api-mock.js, qui fournit les données, à partir de listes écrites en dur ;

  • leave-api-error.js, qui définitLeaveApiError, l’erreur queapp.jsintercepte pour afficher un message.

leave-api-mock.jsexporte cinq fonctions, qui correspondent à tout ce dont la page a besoin :

export async function getBalance(employeeId) { /* … */ }
export async function getRequests(status) { /* … */ }
export async function createRequest(newRequest) { /* … */ }
export async function approve(requestId) { /* … */ }
export async function refuse(requestId) { /* … */ }

Et dansapp.js, une seule ligne choisit la source des données :

import * as leaveApi from './leave-api-mock.js';

Vous reconnaissez le principe d’inversion des dépendances, appliqué au chapitre 3 : le code de la page dépend d’un ensemble de fonctions, et une seule ligne décide de leur implémentation. L’équipe a pu construire et tester toute la page sans attendre l’API. Votre travail consiste à écrire un second fichier,leave-api.js, qui exporte les mêmes fonctions mais appelle vraiment l’API, puis à changer cette ligne. Vous ne modifierez rien d’autre dansapp.js.

Le JavaScript de la page ne connaît pas vos records Java : il manipule les objets que lui renvoieleave-api-mock.js. Quand il recevra du JSON de l’API, ces objets devront avoir la même forme. Avant d’écrire le moindre appel, comparez les deux côtés du contrat :

Critère

La question à vous poser

Ce que vous observez dans Hamac

Noms des champs

Chaque propriété lue parapp.jscorrespond-elle à un champ du JSON ?

app.jslitrequest.days, alors que l’API renvoieworkingDays.

Forme des réponses

Les fonctions renvoient-elles la même structure que l’API ?

Non pour le solde :getBalancerenvoie un nombre, l’API renvoie{ "employeeId": 4, "balance": 4.56 }.

Valeurs

Les valeurs attendues sont-elles celles que l’API produit ?

Oui : la page traduit les codesPENDING,APPROVEDetREFUSED, et les dates sont au format ISO des deux côtés.

Données envoyées

L’objet envoyé correspond-il au DTO d’entrée ?

Oui :createRequestreçoitemployeeId,startDateetendDate.

Erreurs

La page sait-elle lire les réponses d’erreur ?

Non :leave-api-mock.jslève ses erreurs lui-même, il n’a jamais lu de ProblemDetail.

Le décalage entredaysetworkingDaysest dangereux, parce qu’il ne provoque aucune erreur. En JavaScript, lire une propriété qui n’existe pas renvoie simplementundefined. La colonne « Jours » de la page resterait vide pour toutes les demandes, sans message dans la console ni dans les journaux de l’application.

Le réflexe le plus risqué consiste à renommer le champ dans l’API pour faire plaisir à la page. Le contrat est publié : il est décrit dans Swagger UI, utilisé par vos commandes curl et vérifié par les tests. Le modifier pour un seul client casserait tous les autres. C’est au client de s’aligner sur le contrat. Ici, c’est le rôle deleave-api.js: il traduit le JSON de l’API dans la forme qu’attendapp.js, exactement commeleave-api-mock.jsfabriquait des objets à cette forme.

Pourquoi les pages ne lisent-elles pas directement les DTO, sans traduction ? 

Ce serait possible ici, puisque la page et l’API vivent dans le même projet. Maisapp.jsa été écrit avant l’API, et il ne doit pas dépendre de la façon dont le JSON est construit. Si le contrat évolue, seulleave-api.jsdevra changer, et non chaque endroit de la page qui lit une demande. C’est la même séparation qu’entre vos entités et vos DTO, du côté du client cette fois.

Remplacez les données simulées par des appels fetch

Le JavaScript a besoin de l’adresse de l’API. Vous pourriez écrirefetch('/api/leave-requests'), avec un chemin qui commence par/. L’appel fonctionnerait sur votre poste. Mais le jour où l’application serait déployée sous un sous-chemin, par exemplehttps://intranet.example.com/hamac/, ce chemin repartirait de la racine du serveur et perdrait le segmenthamac.

Thymeleaf sait construire les adresses de l’application avec la syntaxe@{…}, qui ajoute automatiquement ce préfixe éventuel. Ajoutez cette ligne dans le<head>du template :

<meta name="api-base" th:content="@{/api/}">

Le navigateur reçoit&lt;meta name="api-base" content="/api/"&gt;sur votre poste, etcontent="/hamac/api/"une fois déployée sous/hamac. Le JavaScript lit cette valeur une seule fois, au chargement du module, et n’a jamais à connaître l’adresse du serveur. Le template utilise déjà la même syntaxe pour chargerapp.js:th:src="@{/js/app.js}".

Dans de nombreux projets, le front-end et l’API sont deux applications distinctes, par exemple une application React surhttp://localhost:5173et une API surhttp://localhost:8080. Le navigateur applique alors la politique de même origine : un script chargé depuis une origine ne peut lire les réponses d’une autre origine que si celle-ci l’autorise explicitement, par un mécanisme appelé CORS (Cross-Origin Resource Sharing). Une origine combine le protocole, le nom d’hôte et le port.

Hamac n’est pas dans ce cas. La page, son JavaScript et l’API sont servis par la même application, surhttp://localhost:8080: les appelsfetchrestent dans la même origine, et le navigateur les autorise sans condition. Vous n’avez rien à configurer.

Le réflexe le plus risqué consiste à ajouter quand même@CrossOrigin("*")sur les contrôleurs, « au cas où », parce que la ligne circule dans de nombreux tutoriels. Elle autoriserait n’importe quel site web à appeler votre API depuis le navigateur de vos utilisateurs, pour un besoin qui n’existe pas.

Et si les pages étaient un jour servies par une autre application ? 

Il faudrait alors autoriser leur origine, et seulement elle. Spring MVC le permet avec la méthodeaddCorsMappingsd’unWebMvcConfigurer, en déclarant l’origine exacte, les verbes utilisés (GETetPOST) et l’en-têteContent-Type, idéalement lus dansapplication.properties. Gardez aussi en tête que CORS ne protège pas votre API : il est appliqué par le navigateur, pour protéger l’utilisateur.curlou un autre serveur l’ignorent complètement. Pour empêcher quelqu’un d’appeler l’API, il faut une authentification, avec Spring Security par exemple, qui sort du cadre de ce cours.

Chaque fonction exportée correspond à une route du contrat. La lecture du solde montre le principe :

const baseUrl = document.querySelector('meta[name="api-base"]').content;

export async function getBalance(employeeId) {
  const balance = await send(`employees/${employeeId}/balance`);
  return balance.balance;
}

L’API renvoie un objet, alors queapp.jsattend un simple nombre : la fonction extrait le champbalance. C’est un détail de la traduction entre le contrat HTTP et ce qu’attend la page, et il reste dans ce fichier.

Vous écrirez les quatre autres fonctions sur le même modèle. Pour la création,fetcha besoin de trois options : la méthodePOST, l’en-têteContent-Type: application/jsonet le corps, converti en texte avecJSON.stringify. Sans l’en-tête, Spring ne sait pas que le corps est du JSON, et répond415 Unsupported Media Type.

Toutes les fonctions passent par une fonction privée du module,send. Si la réponse est un succès, elle lit le JSON. Sinon, elle lit la réponse ProblemDetail et lève uneLeaveApiError, queapp.jssait déjà afficher.

async function send(path, options = {}) {
  const response = await fetch(baseUrl + path, options);
  if (response.ok) {
    return response.json();
  }
  throw new LeaveApiError(await readErrorMessage(response));
}

La vérification deresponse.okn’est pas une précaution de style. Contrairement à ce que l’on pourrait croire,fetchne lève aucune erreur pour une réponse404ou409: du point de vue du navigateur, le serveur a répondu, la requête a donc abouti.fetchn’échoue que si le serveur est injoignable. Sans ce test, la page lirait le JSON d’une erreur comme s’il s’agissait d’une demande, et afficherait une ligne vide dans le tableau.

Gardez un affichage sûr

Les données affichées par Hamac viennent en partie des utilisateurs. Aujourd’hui, ce sont des dates et des nombres. Demain, Samuel demandera sans doute un champ « motif » dans le formulaire, rempli librement par les salariés. Imaginez qu’un salarié y saisisse&lt;img src=x onerror="…"&gt;. Si la page insère ce texte comme du HTML, le navigateur exécute le script qu’il contient, chez chaque manager qui ouvre la liste. On parle d’injection de script, ou XSS (Cross-Site Scripting).

La règle tient en deux lignes, une par endroit où la page affiche des données :

Où la donnée est affichée

À utiliser

À ne jamais utiliser pour une donnée

Dans le template, par Thymeleaf, côté serveur

th:text, qui échappe les caractères spéciaux

th:utext, qui insère le texte tel quel

Dans la page, par JavaScript, côté navigateur

textContent, qui insère du texte

innerHTML, qui interprète le texte comme du HTML

th:texttransforme&lt;en&amp;lt;: le navigateur affiche le caractère au lieu de l’interpréter. Le template de Hamac l’utilise déjà, par exemple pour la date du jour fournie parPageController, etapp.jsremplit le tableau avectextContent. Votre travail consiste à ne pas casser cette règle : quand vous afficherez un message d’erreur de l’API, ou quand vous ajouterez une colonne, utilisez les mêmes outils.

Les messages d’erreur viennent de mon API. Est-ce vraiment un risque de les afficher avecinnerHTML? 

Aujourd’hui, ils sont écrits par vous. Mais un message de validation peut reprendre la valeur envoyée par l’utilisateur, et un message d’erreur peut un jour être produit par un autre composant. La règle « pas de HTML construit à partir de données » est plus simple à respecter qu’une liste d’exceptions à surveiller. Réservezth:utextetinnerHTMLau HTML que vous écrivez vous-même, en dur.

Vérifiez le parcours en français et en anglais

Une fois les données réelles affichées, lancez l’application avec./mvnw spring-boot:run, ouvrezhttp://localhost:8080et rejouez le parcours métier complet. Basculez ensuite la page en anglais avec le sélecteur de langue, et recommencez.

Étape

Ce que vous vérifiez

Ce que vous observez dans Hamac

Solde

Le solde est-il celui de l’API, au bon format ?

Leïla Haddad : « 4,56 » en français, « 4.56 » en anglais.

Tableau et filtre

Le filtre par statut appelle-t-il la bonne route ?

Dans l’onglet Réseau des outils de développement, le filtre « En attente » envoie?status=PENDINGdans les deux langues.

Statuts

Les statuts sont-ils traduits ?

« En attente » ou « Pending », à partir du même code renvoyé par l’API.

Formulaire

Une demande valide apparaît-elle dans le tableau ? Une demande invalide affiche-t-elle un message ?

La demande créée apparaît avec ses jours ouvrés. L’erreur de dates s’affiche.

Approbation

Une seconde approbation est-elle refusée avec un message clair ?

Le message de conflit s’affiche, et le solde ne change pas.

Cette vérification illustre une décision prise sans le savoir dès le chapitre 3 : l’API renvoie des données, la vue se charge de leur présentation. Le statut circule sous forme de code, et le nombre sous forme de nombre JSON, toujours écrit avec un point. C’est le JavaScript de la page qui les traduit et les formate selon la langue choisie. Si l’API avait renvoyé « En attente » ou « 4,56 » sous forme de texte, la bascule en anglais aurait été impossible sans modifier l’API.

Vous remarquerez une limite : les messages d’erreur, eux, restent en français dans les deux langues, car ils sont rédigés par l’API. Pour les traduire, la page devrait associer son propre message à chaque code de statut. Ce n’est pas indispensable pour vendredi, mais c’est exactement le type d’information à transmettre à Tomás : vous la noterez dans le README.

Ajoutez la politique des stages

Samuel vous transmet le dossier de Zoé Mendes : un contrat de stage, qui commence lundi prochain. Ajoutez-la au jeu de données de démonstration, à la fin des salariés desrc/main/resources/data.sql:

INSERT INTO employee (first_name, last_name, contract_type, hire_date, days_taken)
VALUES ('Zoé', 'Mendes', 'Stage', DATEADD('DAY', 7, CURRENT_DATE), 0);

Comme pour Leïla, la date d’entrée est calculée à partir de la date du jour : Zoé arrive toujours dans sept jours, quel que soit le jour où vous lancez l’application. Relancez-la et demandez le solde de Zoé, la salariée n° 6 :

curl -i http://localhost:8080/api/employees/6/balance

L’API répond500, avec le message générique de votreApiExceptionHandler. Le journal, lui, indique la cause :java.lang.IllegalArgumentException: Unknown contract type: Stage. Avec le starter, Hamac aurait attribué 0 jour à Zoé en silence, grâce à sa brancheelse. Vous ne l’auriez découvert qu’à sa première demande de congés.

Ajoutez maintenant la constante qui manque à l’enum :

public enum ContractType {
    PERMANENT("CDI"),
    FIXED_TERM("CDD"),
    APPRENTICESHIP("Alternance"),
    INTERNSHIP("Stage");
    // …
}

Relancez l’application. Cette fois, elle ne démarre même plus. Le message d’erreur, au milieu de la trace, est celui que vous avez écrit au chapitre 4 dans le constructeur du résolveur :

Error creating bean with name 'leavePolicyResolver' ...
Caused by: java.lang.IllegalStateException: 0 leave policies found for INTERNSHIP, expected 1

C’est exactement le rôle de cette vérification : un type de contrat sans politique empêche le démarrage, au lieu de produire une erreur le jour où une stagiaire consulte son solde.

Au chapitre 4, vous aviez prévu qu’une classe annotée@Componentsuffirait pour les stages. Écrivez-la dans le packageleave, sur le modèle de celle des CDD : 2 jours par mois complet de présence.

Avant d’écrire le calcul, regardez la date d’entrée de Zoé : elle est dans le futur. Le nombre de jours écoulés est donc négatif, et la formule des CDD donneMath.floorDiv(-7, 30), soit-1mois complet, et donc un droit de -2 jours. C’est précisément la situation décrite au chapitre 3 avec le principe de substitution de Liskov : toutes les politiques doivent renvoyer un nombre de jours positif ou nul. Votre politique doit donc renvoyer0tant que le stage n’a pas commencé.

Relancez l’application : elle démarre, et le solde de Zoé s’affiche. Le résolveur reçoit désormais quatre politiques, et vous n’avez modifié ni le résolveur, niLeaveService, ni aucun contrôleur. C’est le principe ouvert/fermé en action : Hamac est ouverte à un nouveau type de contrat, et fermée à la modification du code qui fonctionnait déjà.

La politique des stages ressemble beaucoup à celle des CDD. N’est-ce pas une duplication à supprimer ? 

Le calcul des mois complets est bien le même. Mais les deux règles ne disent pas la même chose : celle des CDD vient du droit du travail, celle des stages est une règle interne fixée par Samuel. Elles pourront évoluer séparément, et c’est pour cela qu’elles vivent dans deux classes. Si la définition du « mois complet » devenait plus précise, par exemple en comptant les mois du calendrier plutôt que des périodes de 30 jours, il serait alors utile d’extraire ce calcul dans une méthode commune. Vous remarquerez au passage que la politique des CDD donne elle aussi un résultat négatif pour une date d’entrée future : ne la corrigez pas en silence, signalez-le à Samuel et à Inès.

Documentez l’application pour la prochaine personne

Quand vous êtes arrivé sur Hamac, vous avez passé un chapitre entier à comprendre comment elle fonctionnait. Le README est le fichier que Tomás ouvrira en premier, à la racine du dépôt, pour s’éviter ce travail. Il ne remplace ni le code ni les tests : il répond aux questions que l’on se pose avant de les lire.

Rubrique

La question à laquelle elle répond

Ce que vous écrivez pour Hamac

Présentation

À quoi sert cette application, et pour qui ?

La gestion des congés, utilisée par les salariés, les managers et l’équipe RH.

Démarrage

Que dois-je installer, et quelle commande dois-je lancer ?

Un JDK 25, puis./mvnw spring-boot:run. Maven n’a pas besoin d’être installé : le wrapper s’en charge.

Configuration

Quels réglages puis-je modifier, et où ?

Les propriétés deapplication.properties, dont le taux des CDD, et la variable d’environnement qui le remplace.

Architecture

Où se trouve quoi ? Où dois-je intervenir pour une évolution courante ?

Les packages par fonctionnalité, les pages et leur JavaScript, et la marche à suivre pour un nouveau type de contrat.

Endpoints

Comment appeler l’API ?

Les six routes, avec un renvoi vers Swagger UI.

Tests

Comment vérifier que je n’ai rien cassé ?

./mvnw test, et ce que couvrent les tests.

Règles métier et limites connues

Qui décide des règles ? Que reste-t-il à faire ?

Samuel valide toute règle RH. Jours fériés ignorés, messages d’erreur non traduits, date d’entrée future pour les CDD, base en mémoire.

Le réflexe le plus risqué consiste à rédiger un README exhaustif, qui recopie le code classe par classe. Il sera faux dès la prochaine modification, et personne ne le lira. Visez un document court, qui renvoie vers les sources qui restent à jour d’elles-mêmes : Swagger UI pour le contrat,application.propertiespour la configuration, les tests pour les règles.

Un README se vérifie comme du code. Clonez le dépôt dans un nouveau dossier, suivez les instructions à la lettre, sans rien faire de plus que ce qui est écrit. Chaque fois que vous devez deviner une étape, c’est une ligne qui manque.

À vous de jouer

Inès résume les échéances : « Karim teste la page vendredi, Zoé arrive lundi, et Tomás le mois prochain. Je relis ta branche jeudi soir. »

  1. Ajoutez la balise&lt;meta name="api-base"&gt;dans le templateleave-requests.html.

  2. Créezstatic/js/leave-api.js: les cinq fonctions exportées, la traduction deworkingDaysversdayset la lecture des erreurs ProblemDetail enLeaveApiError.

  3. Dansapp.js, remplacez l’import deleave-api-mock.jspar celui deleave-api.js, sans rien modifier d’autre.

  4. Rejouez le parcours complet en français et en anglais, y compris une double approbation et une demande invalide. Vérifiez qu’aucune donnée n’est affichée avecinnerHTMLnith:utext.

  5. Ajoutez Zoé Mendes àdata.sqlet constatez l’erreur, puis ajoutezContractType.INTERNSHIPet constatez l’échec du démarrage. Écrivez enfinInternshipPolicy.

  6. Écrivez deux tests unitaires pourInternshipPolicy, l’un pour un stage en cours, l’autre pour un stage qui n’a pas commencé, et un test d’API pour le solde de Zoé. Lancez./mvnw test.

  7. Rédigez le README, puis vérifiez-le en suivant ses instructions dans un clone neuf du dépôt.

Point de contrôle : la page affiche les données réelles de l’API dans les deux langues. Le formulaire, l’approbation et le refus fonctionnent, et leurs erreurs s’affichent. Le solde de Zoé vaut0../mvnw testse termine parBUILD SUCCESS, et le README permet de lancer l’application dans un clone neuf. Enregistrez votre travail avec Git.

En résumé

  • Avant de brancher une interface sur une API, comparez ce qu’elle attend à ce que l’API renvoie : un nom de champ différent ne provoque aucune erreur en JavaScript, seulement une valeurundefined. En cas d’écart, c’est le client qui s’aligne sur le contrat publié.

  • Un module dédié aux appels à l’API, qui exporte les mêmes fonctions que les données simulées, les remplace sans toucher au reste de la page ; son adresse se construit avec@{…}dans le template.fetchne lève pas d’erreur pour une réponse4xxou5xx: testezresponse.ok, puis lisez la réponse ProblemDetail pour afficher la vraie raison de l’erreur.

  • Une page servie par la même application que l’API n’a pas besoin de CORS : n’autorisez une autre origine que si elle existe, et seulement elle. Affichez les données avecth:textcôté serveur ettextContentcôté navigateur, jamais avecth:utextouinnerHTML.

  • Avec Strategy et le conteneur Spring, un nouveau type de contrat s’ajoute avec une constante, une classe@Componentet des tests, sans modifier le service.

  • Un README court répond aux questions de la prochaine personne et renvoie vers les sources qui restent à jour : Swagger UI,application.propertieset tests.

Hamac est corrigée, prête à accueillir les stagiaires, et assez lisible pour que Tomás la reprenne sans vous : l’objectif fixé par Inès au premier chapitre est atteint. Il vous reste à vérifier que vous savez appliquer ces réflexes ailleurs que dans Hamac. C’est l’objet du quiz final, qui vous place dans un nouveau contexte.

Et si vous obteniez un diplôme OpenClassrooms ?
  • Formations jusqu’à 100 % financées
  • Date de début flexible
  • Projets professionnalisants
  • Mentorat individuel
Trouvez la formation et le financement faits pour vous