AquilApp
Tech et SaaS

API versioning et gestion du cycle de vie : stratégies pour faire évoluer vos API sans casser vos clients

  • API
  • GraphQL
  • NestJS

Pas le temps de tout lire ?

Votre IA résume cette page en un clic, avec les bonnes questions à nous poser.

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.

Versioning d'API

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égieExempleAvantageLimite
URL/v2/clientsLisible, simple à router et à mettre en cacheUne même ressource change d’adresse
En-têteX-GitHub-Api-Version: 2022-11-28URL stableTest moins direct dans un navigateur
Paramètre de requête/clients?version=2Rapide à mettre en placeRisque d’oubli, cache plus délicat
Type de médiaAccept: application/vnd.exemple.v2+jsonProche des principes RESTComplexe, 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 ?

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.

Outil gratuit · 2 minutes

Transformez votre idée en cahier des charges en 2 minutes

Décrivez votre projet en quelques lignes : l’outil pose les bonnes questions et rédige vos premières user stories avant même de vous demander un e-mail.

Créer mon cahier

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 :

  1. Annoncez la déprécation dans la documentation et par e-mail.
  2. Ajoutez l’en-tête Deprecation aux réponses (RFC 9745, 2025).
  3. Mettez l’en-tête Sunset avec la date de retrait (RFC 8594, 2019).
  4. Suivez l’usage par client et contactez directement les retardataires.
  5. 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 ?

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.

VersionStatutAction
v1DépréciéeEn-tête Sunset actif, retrait dans 6 mois
v2StableCorrectifs de sécurité et de bugs uniquement
v3CouranteNouvelles 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

  • Quelle est la meilleure stratégie de versioning d'API ?
    L’URL convient à la majorité des API publiques, car elle est lisible et simple à mettre en cache. L’en-tête daté convient aux API qui évoluent souvent.
  • Faut-il versionner une API GraphQL ?
    Non, dans la plupart des cas. Vous ajoutez des champs et vous marquez les anciens avec @deprecated.
  • Combien de versions d'API faut-il maintenir en même temps ?
    Deux versions majeures suffisent : la courante et la précédente. Une troisième reste temporaire, le temps de la migration.
  • Quand faut-il changer de version majeure ?
    Vous changez de version majeure à chaque modification incompatible, selon SemVer. Une simple addition compatible ne l’exige pas.

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.

Pour continuer

Solutions Métiers

Application de fidélisation client sur mesure : mécaniques, intégration CRM et ROI mesurable

Une application fidélisation client centralise la gestion des récompenses, les cagnottes de cashback et les interactions omnicanales personnalisées. Selon Bain & Company, augmenter la rétention de 5 % accroît les bénéfices nets de 25 % à 95 % en 2026. Cette solution logicielle supprime les cartes papier obsolètes, valorise les données clients directes et augmente…

Développement sur mesure

Contract testing avec Pact : sécuriser les échanges API dans une architecture microservices

Le contrat testing pact définit une méthode de test automatisée validant les contrats d’API entre microservices distribués. Selon le rapport DORA, les équipes pratiquant les tests de contrats réduisent les incidents d’intégration de 68 % en 2026. Cette approche élimine les tests end-to-end instables, accélère les déploiements indépendants et garantit la compatibilité ascendante des services…

Développement sur mesure

Clean Architecture et architecture hexagonale : structurer votre application pour la maintenabilité

La Clean Architecture et hexagonale sont deux manières d’organiser le code d’une application autour de son métier. Elles placent les règles métier au centre. Donc, elles repoussent la base de données, le framework et l’interface à l’extérieur. Les dépendances pointent toujours vers le centre. Vous remplacez ainsi une technologie sans réécrire le cœur de l’application.…

Projet Mobile

Gamification dans une application mobile en 2026 : mécaniques, UX et mesure du ROI

La gamification application mobile désigne l’intégration de ressorts ludiques au sein d’environnements numériques non vidéoludiques. Selon Gartner, l’application de ces techniques comportementales augmente l’engagement actif de 48 % en 2026. Cette stratégie stimule la rétention quotidienne, accélère l’apprentissage des fonctionnalités et maximise la valeur vie client des services mobiles. Maintenir l’attention des mobinautes face à…

Arnaud Morand, cofondateur et CEO d’AquilApp

Un projet en tête ? Parlons-en 30 minutes avec Arnaud

Un échange sans engagement pour cadrer votre besoin avec un cofondateur, puis un devis chiffré sous 48 h ouvrées.