API versioning et gestion du cycle de vie : stratégies pour faire évoluer vos API sans casser vos clients
Obtenez un résumé intelligent et des insights personnalisés
L’API versioning consiste à numéroter les versions d’une API pour la faire évoluer sans casser les clients existants. Pour une API REST, quatre stratégies existent : l’URL, l’en-tête, le paramètre de requête et le type de média. Pour GraphQL, on fait évoluer le schéma et on marque les champs obsolètes avec la directive @deprecated.
Mais, qu’est-ce qu’une API (Application Programming Interface) ? C’est l’interface qui permet à deux logiciels d’échanger des données. Dès qu’un client en dépend, chaque modification devient un risque. Alors, il faut avoir les bonnes stratégies et mettre en place des règles. AquilApp peut notamment vous aider à concevoir des API que vous soyez un startup, une PME et que vous fassiez partie des grands comptes.
Pourquoi le versioning d’API est-il critique pour votre produit ?
Une modification cassante est un changement qui oblige les clients d’une API à réécrire leur code. Vous ne contrôlez pas ces clients. Ce sont des partenaires, des applications mobiles ou des outils de vos utilisateurs.
Les applications mobiles posent un problème particulier. Vos utilisateurs mettent à jour leur application quand ils le décident. Plusieurs versions de votre application appellent donc votre API en même temps.
Le sujet touche aussi les produits en ligne. Vous voulez créer un SaaS ? Votre API devient un engagement contractuel. Il en va de même pour l’intégration logicielle avec le système d’information (SI) de vos clients.
Quelles sont les 4 stratégies de versioning d’une API REST ?
REST (Representational State Transfer) est un style d’architecture d’API fondé sur les ressources et le protocole HTTP. Il propose quatre façons d’indiquer la version.
| Stratégie | Exemple | Avantage | Limite |
|---|---|---|---|
| URL | /v2/clients | Lisible, simple à router et à mettre en cache | Une même ressource change d’adresse |
| En-tête | X-GitHub-Api-Version: 2022-11-28 | URL stable | Test moins direct dans un navigateur |
| Paramètre de requête | /clients?version=2 | Rapide à mettre en place | Risque d’oubli, cache plus délicat |
| Type de média | Accept: application/vnd.exemple.v2+json | Proche des principes REST | Complexe, peu d’outils compatibles |
Sources : documentation de l’API REST GitHub, documentation de l’API Stripe, Microsoft REST API Guidelines. Synthèse AquilApp.
Nous tranchons ainsi. Choisissez l’URL pour une API publique ou destinée à des partenaires. Ensuite, sélectionnez l’en-tête daté pour une API qui évolue souvent. Stripe applique cette seconde approche avec l’en-tête Stripe-Version.
Numérotez avec le versionnage sémantique. Selon la spécification SemVer 2.0.0, le numéro majeur change pour toute modification incompatible. Seul ce dernier apparaît dans l’URL.
Le framework influence aussi la mise en œuvre. Notre comparatif Express.js vs NestJS détaille le routage par version. Notre guide sur le choix backend complète ce point.
Comment versionner une API versioning sur GraphQL ?
GraphQL est un langage de requête pour API. Ici, le client y choisit lui-même les champs qu’il reçoit. Cette souplesse change la logique de versionnage.
Selon les bonnes pratiques publiées sur graphql.org, une API GraphQL évite le versionnage classique. Elle ajoute de nouveaux champs et laisse les anciens en place. Le client ne reçoit que ce qu’il demande. Donc, l’ajout ne casse rien.
Pour retirer un champ, utilisez la directive @deprecated avec le paramètre reason. Exemple : fullName: String @deprecated(reason: « Utilisez firstName et lastName »). Mesurez ensuite l’usage de chaque champ. Vous supprimez le champ quand plus aucun client ne l’appelle.
Attention cependant aux pièges. Passer un champ de « nullable » à « non nullable » casse les clients. Changer le type d’un champ aussi.
Comment déprécier une API sans perdre vos clients ?
La déprécation est l’annonce officielle qu’une version ou une fonction sera retirée. Elle suit cinq étapes :
- Annoncez la déprécation dans la documentation et par e-mail.
- Ajoutez l’en-tête Deprecation aux réponses (RFC 9745, 2025).
- Mettez l’en-tête Sunset avec la date de retrait (RFC 8594, 2019).
- Suivez l’usage par client et contactez directement les retardataires.
- Retirez la version à la date annoncée, sans exception.
De plus, fixez un délai réaliste. GitHub garantit qu’une ancienne version de son API reste disponible au moins 24 mois après la sortie de la suivante. Nous recommandons au minimum 12 mois pour une API utilisée par des applications mobiles.
Quelles règles garantissent la rétrocompatibilité après une API versioning ?
La rétrocompatibilité est la capacité d’une API à rester utilisable par les anciens clients. Les principes de Google (AIP-180) posent une règle simple : ajouter est sûr, retirer ou modifier est cassant.
Pour des changements sûrs, ajoutez :
- Un champ optionnel dans une réponse ;
- Un nouvel endpoint ;
- Une valeur optionnelle en entrée.
Faites attention à aux changements suivants qui cassent les clients :
- Supprimer ou renommer un champ ;
- Changer le type d’une donnée ;
- Rendre obligatoire un paramètre facultatif ;
- Modifier un code d’erreur ou le sens d’une valeur.
Demandez aussi aux clients d’ignorer les champs inconnus. Cette règle vous laisse la liberté d’enrichir vos réponses.
Comment documenter et suivre les changements d’une API ?
OpenAPI est la spécification standard pour décrire une API REST. Elle contient un attribut deprecated: true qui signale une opération obsolète. Swagger UI affiche cette information à vos utilisateurs.
Tenez un changelog daté, avec une section « modifications cassantes » en tête. Ajoutez également un outil de comparaison comme oasdiff à votre pipeline CI/CD (Continuous Integration / Continuous Delivery). Il compare deux fichiers OpenAPI et bloque toute modification cassante non annoncée.
Cas pratique : comment gérer 3 versions d’API en production ?
Ce scénario illustratif montre une organisation type d’API versioning. Une API compte trois versions actives.
| Version | Statut | Action |
|---|---|---|
| v1 | Dépréciée | En-tête Sunset actif, retrait dans 6 mois |
| v2 | Stable | Correctifs de sécurité et de bugs uniquement |
| v3 | Courante | Nouvelles fonctions, documentation à jour |
Source : scénario illustratif AquilApp.
Vous déployez un seul code pour les trois versions. Une couche de transformation adapte les réponses de v3 au format de v1 et de v2. Vous suivez chaque semaine le trafic par version. Quand v1 passe sous un seuil fixé à l’avance, vous coupez l’accès.
FAQ sur le versioning d'API
Conclusion
L’API versioning protège vos clients et votre calendrier. Donc, choisissez une stratégie claire. Annoncez chaque retrait et automatisez la détection des changements cassants. Ces règles vous permettent de faire évoluer votre produit en confiance.
Vous préparez une API ou vous devez sécuriser la vôtre ? Découvrez notre agence de développement logiciel sur mesure. Notre équipe vous accompagne dès le cadrage.
