Accueil › Fullstack Angular + Spring Boot › Faire évoluer une API sans casser le front
Faire évoluer une API sans casser le front
Conception et entretienavance
Le front n'est pas une application que vous déployez : c'est du code qui tourne déjà chez vos utilisateurs. Un onglet ouvert depuis ce matin exécute la version de ce matin, et appelle votre back de cet après-midi.
Donc : tout changement de contrat doit être compatible, ou mené en plusieurs étapes.
| Changement | Compatible ? |
|---|---|
| Ajouter un champ en réponse | ✅ |
| Ajouter un paramètre optionnel | ✅ |
| Ajouter un endpoint | ✅ |
| Ajouter une valeur à une énumération | ⚠️ le front doit avoir un repli |
| Renommer ou supprimer un champ | ❌ |
Changer un type (number → string) |
❌ |
| Rendre un paramètre obligatoire | ❌ |
| Changer un code de statut ou la forme d'erreur | ❌ |
| Resserrer une validation | ❌ en pratique |
Pour un changement cassant, le procédé en trois déploiements :
public record ProduitDto(
long id,
@Deprecated String nom, // 1. conservé, alimenté
String libelle, // 1. ajouté, alimenté
BigDecimal prix) {
public static ProduitDto de(Produit p) {
return new ProduitDto(p.getId(), p.getLibelle(), p.getLibelle(), p.getPrix());
}
}
- Expansion : les deux champs cohabitent. Ancien et nouveau front fonctionnent.
- Migration : le front passe à
libelle, déployé quand on veut. - Contraction :
nomest retiré, une fois certain que plus personne ne le lit.
Les termes à connaître
- Changement compatible (non cassant)
Modification qu'un client existant peut ignorer sans dysfonctionner : ajout d'un champ en réponse, ajout d'un paramètre optionnel, ajout d'un endpoint. Les champs inconnus étant ignorés par défaut dans Spring Boot comme en JavaScript, l'ajout est sans danger.
- Changement cassant
Modification qui invalide un client existant : suppression ou renommage d'un champ, changement de type, nouveau champ obligatoire en entrée, changement de code de statut ou de forme d'erreur.
- Déploiement décalé (skew)
Période, inévitable, pendant laquelle l'ancien front et le nouveau back cohabitent : le temps du déploiement, et au-delà pour les utilisateurs dont l'onglet est resté ouvert. Un changement cassant se manifeste précisément dans cette fenêtre.
- Expansion puis contraction
Procédé en trois temps pour un changement cassant : (1) ajouter le nouveau champ à côté de l'ancien, les deux alimentés ; (2) migrer les clients ; (3) supprimer l'ancien. Chaque étape est déployable indépendamment.
- Versionnement d'API
Exposer plusieurs versions simultanément, par préfixe d'URL (
/api/v2/...) ou par en-tête. Fiable mais coûteux : deux chemins de code à maintenir et à tester. Réservé aux ruptures véritables, ou aux API consommées par des tiers.- Dépréciation
Signalement d'un élément de contrat encore fonctionnel mais destiné à disparaître :
@Deprecatedcôté Java,deprecated: truedans OpenAPI, et surveillance de l'usage réel pour savoir quand il peut être retiré sans risque.
Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.