Formations — 1 037 leçons en français

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());
    }
}
  1. Expansion : les deux champs cohabitent. Ancien et nouveau front fonctionnent.
  2. Migration : le front passe à libelle, déployé quand on veut.
  3. Contraction : nom est 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 : @Deprecated côté Java, deprecated: true dans OpenAPI, et surveillance de l'usage réel pour savoir quand il peut être retiré sans risque.

Lire l'explication détaillée et faire le quiz →

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.