Les stratégies de gestion des versions des API : la vraie histoire

Vous aurez entendu parler des stratégies de gestion des versions des API si vous fournissez des API. Votre équipe de développement a peut-être eu de nombreuses discussions sur le meilleur choix, mais j'ai une nouvelle. Choisir où placer le numéro de version de votre API n'est pas une décision stratégique.

Le rythme de l'activité et le changement

Votre stratégie de gestion des versions est le résultat des nombreux choix que votre organisation et vos clients ont faits. Il s'agit notamment des segments de clientèle et des secteurs à desservir aux produits et services à proposer.

la relation entre votre organisation et les utilisateurs de vos API est un facteur important. Cela affecte

• la fréquence à laquelle vous modifiez votre API,
• à quelle fréquence vous êtes forcé, ou
• Êtes-vous en mesure d'apporter des modifications ou d'annuler des modifications ?

La manière dont vos utilisateurs d'API accepteront le calendrier de gestion des versions que vous proposez dépend de la structure du pouvoir :

• si les utilisateurs de vos API dépendent de vous, vous pouvez leur dicter quand ils changeront de version ;
• certains consommateurs d'API sont plus puissants et influents, ou
• la relation est très réglementée.

‍

Si vous pouvez apporter des modifications à l'API et que vous souhaitez les introduire en tant que nouvelles versions, vous devez résoudre le problème de savoir comment indiquer un changement de version.

‍

Les fonctionnalités de l'outil dictent votre utilisation des numéros de version

La gestion des versions de l'API est différente de la gestion des versions du code. Il n'est pas acceptable d'augmenter le numéro de version de votre API chaque fois que le code implémentant l'API ou la documentation change. Ce n'est que lorsque l'interface réelle ou, dans certains cas, le comportement change que vous modifiez l'API. Je confonds toujours les gens en disant que les API ont besoin de 2 x DevOps. Ce que je veux dire, c'est que votre API, son interface, éventuellement décrite par une définition OpenAPI, a un cycle de vie, et le code implémentant l'API a son cycle de vie.

Dans une certaine mesure, ils ne dépendent pas l'un de l'autre. Vous pouvez corriger une faute de frappe dans votre définition OpenAPI sans modifier le code ou la logique de calcul du code sans modifier l'interface, par exemple.

Votre code doit utiliser la gestion sémantique des versions, c'est-à-dire que vous devez constamment mettre à jour le numéro de version avec les correctifs majeurs, mineurs et 1.1.1. La discussion sur la gestion des versions des API a tendance à commencer dans les nouvelles équipes ou les nouvelles API par la question suivante : « Devons-nous mettre le numéro de version dans le chemin de l'URI, les paramètres de requête, les en-têtes personnalisés ou utiliser la négociation de contenu ». Mais vous n'avez pas le libre choix à ce sujet. Et vous ne devriez certainement pas le faire car c'est une « bonne pratique de codage ».

À chaque modification du numéro de version de l'interface, les utilisateurs de l'API doivent modifier leur code. Et ça ne leur plaît pas. Cela leur coûte cher et leurs systèmes peuvent tomber en panne, même si le changement ne leur pose aucun problème.

N'oubliez pas de vérifier ce que la technologie et les outils de vos utilisateurs d'API, et plus encore, votre plateforme de gestion d'API, sont capables de gérer. Les outils existants, en particulier, sont difficiles à utiliser et ne peuvent gérer que les numéros de version figurant dans le chemin. Certaines plateformes de gestion des API sont conçues pour prendre en charge les produits ou les plans d'API, dans lesquels les modifications apportées à la version de l'API peuvent être masquées derrière la couche du produit et de l'abonnement.

Si vous utilisez des numéros de version pour indiquer les modifications apportées à votre API, pensez à l'augmenter uniquement si vous introduisez une modification majeure. Et seulement si ce changement brise les clients de leur point de vue. Cela peut parfois prêter à confusion, je l'admets. Dans certains cas exceptionnels, les consommateurs d'API sont confrontés à un changement même si la conception de l'API ne change pas.

L'un de nos clients a subi une interruption de service parce qu'un fournisseur d'API a soudainement modifié la méthode d'authentification de l'API. J'ai vu l'e-mail envoyé par le support des fournisseurs d'API suite à une plainte de notre client. La réponse indiquait que « ce n'était pas un changement d'API ; nous avons simplement modifié l'authentification ». Nous pourrions discuter de la sémantique de cette déclaration, mais en fin de compte, le consommateur de l'API, notre client, a subi une interruption de service. Le changement était donc irrégulier ; il n'était pas rétrocompatible. Il n'y a aucun doute quant à l'expérience du consommateur d'API ici.

Si une fonctionnalité de votre API n'est pas utilisée, elle ne peut pas être interrompue.

Je vous dévoile un secret. S'il n'est pas utilisé, il ne peut pas se casser. Si vous commencez modestement, que vous connaissez les besoins des utilisateurs de votre API, que vous consultez les journaux et les statistiques pour voir si quelqu'un utilise la fonctionnalité que vous êtes sur le point de supprimer ou non, et que vous continuez à ajouter uniquement de nouveaux terminaux et attributs, vous pouvez vous en tenir à la même version majeure et uniquement celle-ci pour les années à venir. Vous n'aurez besoin d'une modification que si vous effectuez une refonte complète affectant un grand nombre ou la totalité des terminaux ou si vous apportez des modifications importantes à la logique métier.

Supposons que vous veniez d'exposer quelques points finaux dotés d'attributs minimaux. Vous êtes sûr que tout est nécessaire, conçu à la perfection et validé auprès des futurs utilisateurs d'API. Pourquoi ne pas ajouter des éléments à la même version d'API et envisager de versionner la documentation ou de mettre à jour les notes de publication ? Ainsi, ceux qui se sont déjà connectés à l'API n'ont pas à modifier leur code et peuvent simplement commencer à utiliser les nouvelles fonctionnalités.

Il existe des cas exceptionnels, comme toujours. Un fournisseur de plateforme a dévoilé de nouveaux groupes de données personnelles provenant d'un terminal existant. Cela a créé une violation de la vie privée et a constitué un changement radical, même si l'interface n'a pas changé. Donc, lorsqu'il s'agit d'ajouter de nouvelles fonctionnalités à l'API, ce n'est pas grave, mais attention à ce que ces fonctionnalités ne soient que des données supplémentaires. Dans cet exemple de cas, le fournisseur d'applications tiers a été exclu de son activité parce qu'il n'était pas autorisé à utiliser l'API après que les clients aient découvert le problème de confidentialité. Et le fournisseur d'applications utilisant l'API n'avait rien fait de mal, sauf qu'il aurait peut-être dû appliquer de meilleures politiques de test.

Votre équipe d'API est-elle donc suffisamment mature pour produire un minimum de versions viables et réaliser une conception et un développement d'API de qualité ? Cela aura un impact sur votre besoin d'introduire des modifications importantes ou sur votre capacité à les éviter. Évaluez les capacités de l'équipe en matière de recherche et de vision des besoins futurs des consommateurs d'API. Où se dirigent vos produits API ou les ressources, services ou produits qu'ils exposent ?

‍

Les stratégies évolutives de gestion des versions des API

Au niveau stratégique, la gestion des versions de votre API doit évoluer en fonction de l'évolution des attentes en matière de création de valeur de vos utilisateurs d'API, c'est-à-dire de vos équipes internes, de vos clients ou de vos partenaires.

Vous avez peut-être commencé avec une « API Company X ». Vous vous rendez alors compte que ce sera trop important et que cela exposera trop à un trop grand nombre de segments de consommateurs. En tant qu'entreprise, vous pourriez évoluer pour proposer plusieurs variantes de SaaS, de données ou d'autres produits ou services auxquels votre API est étroitement liée. Vous divisez donc votre API par produit et par version en fonction des versions de vos produits.

Ensuite, vous vous rendez compte qu'il existe certains points finaux qui

a) sont communs à de nombreux produits ou

b) sont limités à certains segments spécifiques de consommateurs d'API.

c) devrait avoir des prix différents de ceux des autres.

Vous finissez donc par diviser vos produits API en fonction de propositions de valeur ou de cas d'utilisation.

Cela devrait être facile compte tenu de votre connaissance approfondie des clients, des partenaires et des consommateurs des API, ainsi que de votre feuille de route globale et de votre vision du produit. J'espère que vous les avez. La question qui se pose est la suivante : comment envisagez-vous l'évolution de votre API ? Quelles ressources expose-t-il et quel est son cycle de vie ? Cela fait une différence si l'API est connectée à une voiture au lieu d'un algorithme d'apprentissage automatique dans le cloud. Cette dernière sera plus facile et plus rapide à modifier si l'API change.

En fin de compte, vous faites les choses correctement et offrez une API fantastique. Les utilisateurs de votre API n'ont pas remarqué que votre API tombait souvent en panne (même si vous avez introduit toutes les modifications nécessaires). Vous fournissez une feuille de route claire basée sur une bonne compréhension des API par les consommateurs. Les consommateurs de vos API devraient être ravis et informés. Ils innoveront avec vous et vous aideront à créer votre feuille de route. Ils s'engagent à apporter des modifications ou à adopter les nouvelles fonctionnalités que vous offrez. Après tout, ils collaboraient au processus.

J'espère que vous vous sentirez inspiré la prochaine fois que vous aurez à réfléchir aux stratégies de gestion des versions des API !

‍