Versionner et déprécier proprement

Prérequis : cours 5.1 (REST mature).

Pourquoi

Une API utilisée ne s'arrête pas : elle évolue. Sans discipline, chaque release casse un client silencieux qu'on découvre au pire moment. Versionner, c'est promettre ; déprécier, c'est prévenir.

Concepts

• Compatibilité : ajout de champ/endpoint = compatible ; renommer, supprimer, changer le sens/le type = rupture. Toute rupture exige une version majeure + migration des clients.
• Version dans l'URL (/v1/, /v2/) : simple, explicite, cachable. Alternative : négociation par header — plus pure, moins lisible. Pour une API solo/équipe : URL, sans hésiter.
• Dépréciation : annoncer (Sunset header + date + changelog + logs d'usage), mesurer (qui appelle encore ?), puis retirer. Jamais l'inverse.
• Contrat testé : tests de contrat (Pact, ou snapshots de réponses) qui cassent en CI si le provider change un champ consommé. La promesse vérifiée par machine.

Exemple : le cycle de vie d'un champ

v1 : { "name": "x" }
v1.1 : { "name": "x", "full_name": "x" } + Sunset: name (docs + logs)
v2 (6 mois plus tard, usage name = 0 %) : { "full_name": "x" }

Cas réel

Champ phone renommé en phone_number « évident » un mardi : l'app mobile (30 % des users pas à jour) crash au login pendant 3 jours. Avec dépréciation mesurée : double champ 2 versions, zéro crash, retrait quand l'usage tombe à zéro.

Pièges

• « Personne n'utilise ce champ » (sans mesure) : quelqu'un l'utilise toujours. Mesurer d'abord.
• v2 qui duplique TOUTE l'API pour 2 champs : versionner par ressource quand possible, pas en bloc.
• Sunset sans date : une dépréciation sans deadline ne meurt jamais.

À retenir

Ajouter ok, casser = version majeure ; déprécier (annoncer, mesurer, retirer) ; contrats testés en CI.