J’ai fini de regarder une série de leçons sur la conception et la gestion des versions des API HTTP/REST de l’auteur bien connu Jeffrey Richter, qui est l’auteur des best-sellers CLR via C# et API Windows via C++.
Pour ceux qui conçoivent des API back-end, je recommande vivement de le regarder (et de lire les livres également, si ce n’est pas le cas), en particulier ceux qui pensent que faire une API est simple (probablement impressionnés par plusieurs « Hello, World ! » prototypes réalisés pendant les week-ends).
Une chose importante à noter dans cet article est qu’il est vraiment important de combinez un peu de pratique lorsque vous faites un apprentissage théorique.
Cette recommandation fonctionnera pour les développeurs de tout niveau d’expérience et ne dépend pas de la notoriété de l’auteur du livre/du cours. Il est toujours facile de regarder et de lire quelque chose et de mettre un signe « appris » dessus, mais la mise en œuvre réelle posera toujours des obstacles, et c’est là que les choses deviennent vraiment intéressantes.
Maintenant, prenons un conseil du cours et plongeons dans la partie qui couvre le sujet de la gestion des versions des API HTTP.
API REST Partout
La plupart des API publiques utilisent des approches REST ou RESTful. Ces protocoles gRPC, SOAP, GraphQL et autres sont bons pour leurs propres besoins, mais REST couvre la plupart des besoins :
- Il est disponible pour tout type de client : anciens/nouveaux navigateurs, smartphones, ordinateurs bas de gamme, Raspberry Pis et même consoles.
- Il utilise un langage HTTP bien connu pour toutes les fonctionnalités dont une API a besoin, comme la gestion des erreurs, la transmission de jetons d’authentification (en-têtes), le transfert de tous les types de contenu, le contrôle de la bande passante, etc.
- De nombreux exemples sont disponibles sur internet
Et, pour dire vrai, pour les prototypes et les entreprises locales, un développement rapide et bon marché est tout ce dont vous avez besoin. Tous les autres protocoles ont été créés pour répondre à des besoins beaucoup plus spécifiques comme la mise à l’échelle, la gestion des canaux à faible bande passante, les solutions d’entreprise, etc.
Mais cette simplicité et ce bas seuil d’entrée jouent un mauvais rôle en ce qui concerne la qualité du produit de votre API publique. Très peu de développeurs non seniors savent que les API publiques doivent être rétrocompatible et parfois même compatible en avant. Une infime partie des développeurs sait comment y parvenir.
Quel est le problème avec les API publiques ?
La gestion des versions d’API joue un rôle crucial pour rendre votre API vraiment attrayante pour vos clients satisfaits. Depuis que vous avez publié votre API pour la première fois, les choses n’ont jamais été amusantes pour vous.
Vous devez maintenir toutes les bases des clients depuis la version 1.0-pre-alpha jusqu’à la version 99999…9.0, sauf si vous avez été assez malin pour publier votre politique d’utilisation de l’API publique. N’est-ce pas? 🙂
Dans cette politique, vous pouvez recommander à tous vos clients de mettre à jour chaque version, mais il ne s’agit toujours que d’une recommandation. Vous ne pouvez pas non plus garantir la stabilité de vos anciennes versions, mais cela dépend vraiment de vos relations clients.
De toute façon, vous devez étiqueter votre version d’API et vous assurer que les clients comprennent potentiellement comment cela fonctionne en fonction de la documentation et des politiques que vous avez fournies.
Suivez simplement les recommandations de quelqu’un dans la gestion des versions d’API : qu’est-ce qui peut mal tourner ?
Une version d’API est une étiquette qui doit dire à vos clients à quoi s’attendre. Il existe différentes façons de le faire, pour n’en citer que quelques-unes :
- http://api.tactica.xyz/products?api-version=0.1-alpha
- http://api.tactica.xyz/products?api-version=1.0
- http://api.tactica.xyz/products?api-version=2023-01-01
- http://api.tactica.xyz/v0.9-beta/products
- http://api.tactica.xyz/v1.0/products
Comme vous pouvez le voir, il existe de nombreuses façons d’indiquer votre version d’API au client, et avant de prendre la première approche de la liste, je dois vous dire que ce n’est pas toujours « à vous de décider ». Passons en revue pourquoi vous voudrez peut-être utiliser l’un ou l’autre moyen.
Fondamentalement, il n’y a que 2 approches qui diffèrent de manière significative :
- Mettez votre version d’API dans l’URL.
- Mettez votre version d’API dans les paramètres.
Dans diverses sources, j’ai vu l’approche n ° 1 marquée comme obsolète. Cependant, il y a encore des raisons de continuer à l’utiliser. Passons en revue ceux-ci.
Pourquoi passer une version dans l’URL
Pourquoi passer une version en paramètre
- Nous pouvons garantir la stabilité des chemins d’URL de leur API REST, même dans les futures versions de l’API.
- Vous pouvez toujours renvoyer une ressource DEFAULT sans même spécifier de version. etc.
- Passez facilement de -preview ou -beta à la version publiée et rendez ainsi votre développement un peu plus agile et itératif.
- Donne Suite transparence envers les clients -> plus d’informations sur la date de sortie
- Séparez API BEHAVIOUR de RESOURCE.
- Prend en charge la fonctionnalité de gestion des versions de groupe qui permet aux développeurs de rechercher un numéro de version unique et de l’utiliser sur plusieurs points de terminaison. Les numéros de version du groupe sont bien connus et les services devrait rejeter toutes les valeurs non reconnues.
Phew. Pas mal de notes, ha ?
Ce qui est amusant, c’est que rien de tout cela n’est réellement mentionné dans le cours. C’est pourquoi je voulais apporter cet exemple du besoin de questions, qui apparaissent juste après avoir commencé à pratiquer.
Plus à considérer pour l’API publique
L’approche de la gestion des versions d’API ne doit pas être une réflexion après coup. Chaque fois que vous souhaitez modifier un paramètre obligatoire, le format de la charge utile, remplacer certains anciens codes d’erreur ou modifier un comportement, pensez à ajouter de nouvelles méthodes d’API et à publier de nouvelles versions.
Ce serait encore mieux si vous intégriez les numéros de version dans la structure de données. Vous n’en aurez peut-être pas besoin au début, mais vous vous en remercierez lorsque vous voudrez évoluer (architecture événementielle, etc.).
Conclusion
Le respect de ces règles rendra vos clients API publics plus heureux et votre vie un peu plus facile (mais c’est encore beaucoup).
Comme vous pouvez le remarquer, en général, il y a beaucoup de « à vous de décider » dans la gestion des versions de l’API, à partir des politiques et jusqu’aux détails techniques, mais cela ne fait généralement pas partie d’un livre ou d’un cours et c’est quelque chose que vous avez à résoudre par vous-même.
La prochaine fois, avant de terminer ton stage, prends le temps de t’entraîner un peu. Je suis sûr que vous trouverez de nombreux endroits pour lever la main et discuter avec vos collègues expérimentés ou une communauté.