API Versioning : comment faire évoluer une API sans compromettre les intégrations existantes?

Une API peut commencer par remplir une fonction relativement simple : une application demande des données et un autre système les lui fournit.

Avec le temps, les choses évoluent. De nouveaux champs sont ajoutés, la structure des données change, les fonctionnalités s’améliorent et de nouveaux besoins apparaissent.

Mais une difficulté se pose : l’API peut avoir évolué alors que les systèmes qui l’utilisent, eux, n’ont pas encore changé.

Lorsque plusieurs applications, plateformes ou services sont intégrés à une même API, une modification qui semble mineure peut affecter plusieurs systèmes à la fois.

C’est précisément là qu’intervient l’API Versioning.

Lorsqu’un petit changement affecte plusieurs systèmes

Prenons un exemple simple.

Une API renvoie les informations d’un client, telles que son nom, son adresse et son numéro de téléphone. Par la suite, la structure doit évoluer parce que le système nécessite une nouvelle façon d’organiser les données relatives aux adresses.

Pour une nouvelle application, cette évolution peut constituer une amélioration. Mais une application existante peut toujours s’attendre à recevoir les données selon la structure précédente.

Si l’API est modifiée directement, l’intégration existante risque de ne plus fonctionner comme prévu.

C’est pourquoi le développement d’une API ne consiste pas uniquement à introduire de nouvelles fonctionnalités. Il faut également tenir compte des systèmes qui dépendent de son fonctionnement actuel.

Une nouvelle version peut coexister avec la version actuelle

L’API Versioning permet de gérer cette évolution de manière contrôlée.

Plutôt que de remplacer immédiatement la version existante, une nouvelle version peut être introduite. Par exemple, les systèmes existants peuvent continuer à utiliser v1, tandis que les nouvelles intégrations ou celles qui ont été mises à jour passent à v2.

Ainsi, le changement n’a pas besoin d’être appliqué à l’ensemble de l’écosystème au même moment.

Les équipes disposent du temps nécessaire pour adapter leurs intégrations, tester la nouvelle version et planifier progressivement la transition. La version précédente peut continuer à être prise en charge pendant une période définie et n’être retirée que lorsque les systèmes qui en dépendent sont prêts.

Tous les changements ne nécessitent pas une nouvelle version

L’API Versioning ne signifie pas que chaque amélioration doit donner naissance à v2, v3 ou v4.

De nombreuses évolutions peuvent être apportées tout en maintenant la rétrocompatibilité, sans modifier la manière dont les systèmes existants communiquent avec l’API.

Une nouvelle version devient nécessaire lorsqu’une évolution ne peut pas être introduite sans modifier le contrat existant de l’API.

C’est pourquoi le versioning ne se résume pas à une convention de nommage. Il fait partie intégrante de la manière dont l’évolution d’une intégration est conçue et gérée.

Une API doit aussi être conçue pour évoluer

Pour une entreprise de développement logiciel, une bonne intégration ne consiste pas simplement à connecter deux systèmes qui doivent communiquer aujourd’hui.

Les systèmes évolueront. Les applications seront mises à jour. Les besoins métier changeront.

L’architecture doit donc prévoir ces évolutions afin que chaque mise à jour ne devienne pas un problème pour les autres systèmes.

Comme l’explique Ermal Beqiri, fondateur de Soft & Solution Group :

“Une API bien conçue doit permettre au système d’évoluer tout en assurant le bon fonctionnement des intégrations existantes et en permettant une transition maîtrisée vers les nouvelles évolutions.”

L’API Versioning ne consiste pas simplement à gérer différentes versions. Il s’agit de concevoir des intégrations capables d’évoluer sans compromettre le fonctionnement des systèmes existants.