Mettre le design au centre de la gouvernance d’API
Une architecture d’API basée sur une approche Design-First permet de mettre l’utilisateur final au cœur de la conception et ainsi de penser l’utilisation qui en sera faite. Une telle approche permet d’avoir un retour plus rapide des potentiels utilisateurs sur la base de l’utilisation qui sera la leur et d‘effectuer les modifications en conséquence sans avoir à attendre le long cycle qu’est celui du développement, de la construction et du déploiement.
Les architectures API sont d’autant plus plébiscitées que les entreprises sont nombreuses à ouvrir leurs données à des applications tierces dans l’objectif de tirer le meilleur parti de ces données et de dégager une stratégie de monétisation. La spécification OpenAPI communément appelée « Swagger » donne un standard pour la conception des APIs afin que toute entreprise utilisant cette dernière ait la garantie d’avoir une API comprise de tous et facilement interprétable par les différents outils du marché.
Ces spécifications étant le point d’entrée dans une approche Design-First, il devient intéressant d’avoir un outil tel que Stoplight pour isoler la phase de conception des autres phases. Un tel outil permettra à différentes catégories de profils d’apporter de la plus value lors de la phase de conception et d’avoir les feedbacks au plus tôt lors de la conception.
Une API correctement spécifiée facilitera grandement le travail des développeurs du backend, des personnes qui devront consommer l’API ou tout simplement des curieux qui voudraient comprendre le rôle de l’API.
Gagner en productivité avec Stoplight
Tandis que certaines entreprises préféreront adopter une solution complète d’API Management qui leur permettra de gérer le cycle de vie des API et bien plus, d’autres souhaitent capitaliser sur l’architecture déjà en place et une ingénierie bien éprouvée par la DSI.
Indépendamment de l’approche choisie, le design et la documentation reste un élément indispensable d’une bonne stratégie d’API. Que ce soit dans une approche Design-First ou Code-First, il est très important de penser la communication qui sera faite autour des APIs : comment les partenaires vont interagir avec notre APIs et avec quelle facilité la prise en main se fera.
Stoplight fournit un produit permettant répondre à ces besoins :
● Design d’API : Grâce à son interface visuel, il est possible de concevoir des APIs sans connaissances particulières sur la spécification OpenAPI. Cette conception est d’autant plus facilitée par Spectral (logiciel open source) qui notifie l’internaute en cas d’écart avec la spécification OpenAPI. Cet outil visuel permet notamment d’accélérer la phase de conception.
● Test d’API : Stoplight au travers du logiciel open source Prism, permet de tester directement l’API conçue à grâce à des mocks qu’il est possible de générer.
● Documentation : en plus du Swagger généré à la suite du design, il est possible rédiger une documentation plus explicite.
Il est possible d’utiliser Stoplight dans sa version web ou bureau avec Stoplight Studio.
La documentation peut être partagée entre les différents projets, permettant ainsi à toutes les équipes de travailler sur une base commune. Ces derniers pourront y consulter l’ensemble des modèles de données exposées et comprendre les possibilités offertes par l’API grâce à une documentation claire et épurée.
API design-first approach vs traditional service design
(Source : https://hub.packtpub.com/implementing-an-api-design-first-approach-for-building-apis/)
Alternative à Stoplight
Il est prudent de signaler que Stoplight ne joue pas le rôle d’un portail développeur, en ce sens qu’il n’offre pas la possibilité de souscrire aux API ou de les surveiller depuis son interface. L’utilisation de Stoplight se limite actuellement à la conception et la documentation des APIs
Il n’est pas pertinent de comparer Stoplight avec les solutions APIs management qui couvrent un périmètre plus large allant de la conception à la monétisation en passant par la sécurisation des API.
Afin d’aller plus loin dans la gouvernance des API sans supporter le coût d’intégration d’une plateforme d’API management, l’entreprise peut utiliser des solutions plus légères et embarquant plus de fonctionnalités que Stoplight.
Le tableau ci-dessus présente un comparatif avec 2 autres solutions :
1- SwaggerHub : solution très connue sur le marché des API, notamment pour les possibilités de tests offertes par la solution
2- Apiary : une solution d’Oracle Cloud similaire à Stoplight et qui permet notamment d’avoir des métriques sur les API testées
