Versioning API : gérer l'évolution sans casser vos clients

Vous avez lancé votre API métier il y a six mois. Tout fonctionne bien. Sauf qu'aujourd'hui, vous devez ajouter de nouveaux champs, modifier la structure d'une réponse, ou retirer un endpoint obsolète. Le dilemme classique : comment faire évoluer sans que vos clients—intégrateurs externes, applications mobiles, partenaires—se retrouvent face à des erreurs 500 ?

Le versioning d'API n'est pas qu'une question technique. C'est un engagement de stabilité envers ceux qui dépendent de votre système.

Pourquoi le versioning pose problème en production

Beaucoup de PME lancent une API sans stratégie de versioning claire. Les premiers mois, ça passe. On ajoute un champ optionnel ici, on renomme une clé là. Les clients compatissants mettent à jour leurs intégrations. Mais au fil du temps, c'est le chaos : certains clients restent bloqués sur une ancienne version, d'autres cassent à chaque mise à jour, et votre équipe passe son temps à maintenir plusieurs implémentations en parallèle.

Le vrai coût : chaque breaking change force vos clients à intervenir. Pour une PME qui a intégré votre API dans son processus critique, c'est un événement. Un site e-commerce qui dépend de votre service ne peut pas se permettre une panne de trois heures parce que vous aviez renommé un paramètre.

Les trois stratégies principales

1. Versioning dans l'URL (v1, v2, v3)

C'est l'approche la plus simple et la plus courante. Vous exposez /api/v1/, puis /api/v2/ selon vos besoins. Les avantages sont évidents : c'est très lisible, vos clients savent exactement quelle version ils utilisent, et vous pouvez maintenir deux versions sans confusion.

Le revers : vous finissez par maintenir plusieurs copies du même code. Si vous devez corriger un bug de sécurité en v1, il faut le corriger aussi en v2 et v3. C'est coûteux en effort technique.

2. Versioning dans l'en-tête HTTP

Au lieu de toucher l'URL, le client envoie un en-tête du type Accept-Version: 2.0 ou X-API-Version: 2. C'est plus « propre » en apparence : vos URLs restent stables, votre API semble unique.

Mais cela crée une fausse simplicité. Les debugging become harder: un client oublie de spécifier l'en-tête, et vous ne savez pas quelle version est appelée. Les outils de test (Postman, navigateur) doivent être configurés différemment. Et côté métier, c'est moins transparent.

3. Versioning sémantique sans rupture (API Forward-Compatible)

C'est l'approche que préfèrent les géants comme Stripe ou Slack : une seule URL, mais l'API évolue de façon « non-cassante ». Vous ajoutez toujours des champs, jamais vous n'en supprimez. Les clients ignorent les champs qu'ils ne comprennent pas. Vous dépréciez un endpoint six mois à l'avance, puis le retirez après une période de grâce explicite.

C'est la plus exigeante, mais aussi la plus professionnelle. Elle nécessite une discipline de conception stricte dès le départ.

Bonnes pratiques pour votre versioning

Dépréciation explicite : Avant de casser un endpoint, annoncez-le six mois à l'avance dans votre documentation et via une notification. Un header Deprecation: true et Sunset: date-du-retrait aide aussi.

Changelog détaillé : Chaque version doit avoir un changelog lisible. Listez les breaking changes en rouge, les nouveautés en vert. Pas de surprise.

Outils de monitoring : Vous devez savoir combien de clients utilisent encore chaque ancienne version. Avec un dashboard simple, vous pouvez envoyer des notifications ciblées aux clients qui traînent.

Documentation par version : Ne gardez pas qu'une seule documentation. Si vous maintenez v1 et v2, avoir deux docs côte à côte (ou switchable) aide vos clients à migrer.

Cas pratique : l'évolution d'une API métier

Imaginons que vous exploitez une API d'intégration pour des partenaires WooCommerce. Vous aviez un endpoint /api/v1/orders qui retournait simplement l'identifiant, la date et le montant. Maintenant, vous voulez ajouter des données client enrichies.

Approche non-cassante : vous ajoutez un paramètre optionnel ?include=customer. Les anciens clients reçoivent la réponse historique. Les nouveaux clients activent l'option et obtiennent les données supplémentaires. Zéro casse.

Approche avec versioning : vous lancez /api/v2/orders avec la nouvelle structure. Vous maintenez v1 en lecture seule pendant douze mois, puis retirez. C'est plus simple si la structure change radicalement, mais plus coûteux à maintenir.

Intégration avec votre stack existant

Si vous avez une architecture microservices ou une application SaaS multi-tenant, le versioning d'API devient encore plus critique. Chaque client peut être sur une version différente, et vous devez router intelligemment selon l'en-tête ou l'URL.

Pour les équipes utilisant Dolibarr ou des intégrations personnalisées, un bon versioning API permet de connecter des outils externes sans crainte : ils savent que votre contrat d'interface tiendra six mois, douze mois, sans surprise.

Résumé : comment décider

Choisissez le versioning dans l'URL (/v1/, /v2/) si vous démarrez ou que vos clients sont nombreux et variés : c'est transparent et rassurant. Passez au versioning forward-compatible si vous maîtrisez votre design API et que vous pouvez garantir la rétro-compatibilité.

L'essentiel : documentez votre choix, déclarez vos cycles de dépréciations, et notifiez vos clients. Une API fiable, c'est une API prévisible.

Vous avez une API qui évolue rapidement ou des clients qui se plaignent des ruptures ? Parlons ensemble de votre stratégie de versioning.

Questions fréquentes