Articles
Créer un catalogue d'API interne avec Atlassian Compass
Katie Silver
PRINCIPAL PRODUCT MANAGER, ATLASSIAN
Synthèse
Le résumé exécutif va ici
Durée
4 minutes de lecture. Moins de 10 minutes pour configurer Compass.
Public
Vous faites partie d'une équipe de livraison de logiciels et utilisez des API. Les développeurs, les ingénieurs et bien d'autres professionnels peuvent tous en bénéficier.
Prérequis
- Obtenir Compass. L'essai est gratuit et le démarrage ne prend que quelques minutes.
Créer un catalogue d'API précis est un véritable casse-tête
Au cours de la dernière décennie, nous avons troqué les gros systèmes monolithiques contre des microservices, des architectures distribuées et des équipes autonomes. Les avantages sont réels, mais les conséquences le sont tout autant. Autrefois, les compilateurs typés et les tests permettaient d'assurer la bonne interaction entre toutes les parties d'une base de code volumineuse. Aujourd'hui, ce sont les API qui constituent les frontières, et il n'est pas certain qu'elles s'intègrent toutes parfaitement une fois déployées.
Nous savons que les développeurs travaillent plus vite et que les équipes livrent de meilleurs produits lorsque tout le monde comprend comment les API fonctionnent et quand elles évoluent. C'est le suivi et la maintenance de cette documentation qui posent problème.
Chaque organisation se situe à un niveau de maturité différent lorsqu'il s'agit de cartographier ses services. Dans certaines équipes, les discussions sur Slack permettent d'aligner les producteurs et les consommateurs d'API. Dans d'autres équipes, le fonctionnement de chaque API est consigné lors de la création du service, mais n'est jamais actualisé. Si vous disposez de bons processus ou outils, chaque API est documentée et ses changements sont automatiquement communiqués aux autres parties prenantes.
Où que vous en soyez dans ce parcours, Compass, la nouvelle plateforme de développement d'Atlassian, peut vous aider.
Documentation d'API centralisée avec Compass
Où la documentation d'API doit-elle se trouver dans l'univers des microservices ? Ce n'est pas parce que nous concevons et déployons nos services séparément que nous voulons que chaque service dispose de son propre site de documentation hébergé, ou d'un fichier OpenAPI stocké dans un emplacement obscur. Les équipes souhaitent rassembler toutes ces informations et les rendre consultables sans avoir à déployer d'énormes efforts en interne pour créer un registre d'API.
Compass vous permet de centraliser facilement toute votre documentation d'API en une heure, et non plus en une semaine ou un trimestre. Vous n'avez pas besoin de télécharger manuellement la documentation à chaque changement, il vous suffit de connecter votre SCM (Bitbucket, GitHub ou GitLab) à Compass.
En quelques minutes, Compass analysera tous vos dépôts à la recherche de fichiers OpenAPI et les publiera dans votre catalogue. Toutes les API de toutes vos équipes deviennent immédiatement centralisées et consultables.
Découverte et intégration d'une API
Imaginez qu'un développeur se voie attribuer un ticket pour créer un flux de remboursement. Il sait qu'il doit trouver l'API appropriée pour traiter un remboursement, mais il ne sait pas par où commencer. Dans de nombreuses entreprises, il poserait la question sur Slack et attendrait potentiellement des heures qu'un collègue à l'autre bout du monde réponde à ses questions sur l'API à utiliser. Dans les équipes utilisant Compass, tout ce processus peut être géré en libre-service. Les développeurs peuvent rechercher des points de terminaison d'API et trouver les informations exactes dont ils ont besoin directement dans Compass en quelques secondes seulement. Ainsi, le développeur qui recherche des informations les trouve plus rapidement, et l'équipe qui possède l'API en question subit moins d'interruptions.
Être informé des changements d'API
Dans l'univers des microservices, chaque service se déploie de manière autonome, subissant parfois des changements dont les utilisateurs doivent être informés. Heureusement, Compass ne se contente pas de connaître la documentation de votre API, il sait également comment celle-ci évolue au fil du temps. Chaque fois qu'un collègue merge une pull request qui actualise la documentation de votre API, Compass actualise également sa version de la documentation, de sorte que la version que les développeurs voient dans Compass correspond toujours à l'API la plus récente.
L'historique des changements apparaît même sur la page du journal des changements, pour vous permettre de voir quand des changements importants ont eu lieu par le passé.
Lorsque les développeurs disposent de la bonne documentation, le code est livré plus rapidement
Dans la récente enquête de Postman auprès des développeurs d'API, 52 % des développeurs ont déclaré que le plus grand problème auquel ils étaient confrontés lorsqu'ils travaillaient avec des API était l'absence de documentation. L'absence de documentation ralentit le développement, complique l'intégration des nouveaux ingénieurs et rend les logiciels moins fiables.
Si vous deviez créer votre propre catalogue d'API interne, ce serait un projet colossal, avec de nombreux éléments mobiles. Nous avons fait tout ce travail pour vous : un hub de documentation centralisé est à votre disposition en quelques minutes.
Donnez à votre équipe les informations dont elle a besoin et observez-la livrer plus rapidement 🚀.