Le versioning est une decision produit
Le versioning ne concerne pas que la technique. Il determine comment vos clients vivent le changement.
Si vos clients mettent du temps a mettre a jour, prevoyez une longue fenetre de support.
Compatibilite avant tout
La meilleure strategie est d'eviter les ruptures. Ajoutez des champs optionnels et gardez les comportements par defaut.
Moins de versions actives signifie moins de support et plus de stabilite.
Versioning par URL
Le versioning par URL (`/v1/users`) est visible et simple. C'est la solution la plus courante.
Le risque est d'en abuser. Creer une nouvelle version est couteux : faites-le rarement.
Versioning par header ou media type
Versionner via headers garde les URLs propres : `Accept: application/vnd.example.v2+json`.
C'est elegant mais moins pratique pour le debug et la mise en cache.
Versioning par query param
Le parametre `?version=2` est simple mais ambigu. Il peut etre confondu avec un filtre.
A reserver aux transitions courtes.
Politiques de deprecation
Annoncer les deprecations est indispensable. Ajoutez des warnings, publiez une date de fin et un guide de migration.
Une politique claire evite les migrations d'urgence.
Tests et compatibilite
Les tests de contrat detectent les changements non prevus. Ils protègent vos clients.
Si possible, faites du shadow traffic pour detecter les regressions avant la mise en prod.
Recommandation pratique
Versionnez uniquement si la rupture est inevitable. Gardez peu de versions actives et des dates claires.
Traitez une nouvelle version comme un lancement produit.