Concevoir ses APIs avec Stoplight : un tour d’horizon

18 juin 2024

Stoplight est un outil de conception d’API qui permet aux développeurs de créer, de documenter et de tester des API de manière efficace et collaborative. Il embarque les fonctionnalités que l’on retrouve en partie sur les outils accélérateurs de développement d’API tels que Postman, SoapUI ou encore l’écosystème Swagger.

Quelles sont les caractéristiques spécifiques de l’outil et ses limites le cas échéant ?

Comment se positionne-t-il par rapport à des outils implémentant des fonctions comparables ?

Étape 1 : Créer un nouveau projet

Stoplight permet de créer de nouveaux projets sous la spécification OpenAPI. A noter que GraphQL ou AsyncAPI ne sont pas encore supportés. L’outil pouvant s’interfacer avec GitLab, GitHub, BitBucket ou encore Azure DevOps, il est aussi possible d’importer des projets existants.

Étape 2 : Définir l’API

Une fois le projet créé, il faut maintenant définir notre API. Il est possible soit de la créer (fichier format JSON ou YAML), soit d’importer un fichier de spécification OpenAPI, ou une collection Postman. Diverses versions d’OpenAPI sont supportées (2.0, 3.0 et 3.1 à l’heure de la rédaction de cet article).

On pourra définir des modèles d’objets communs à notre projet ou spécifiques à une API. L’édition des endpoints, des paramètres et des réponses se fera facilement soit en utilisant la vue formulaire, soit la vue code, dans tous les cas avec une preview en temps réel.

Pour bien garder à jour notre projet, en se branchant par exemple à GitHub, il est possible de configurer les échanges souhaités et ainsi de mettre à jour l’API à chaque changement de Git et vice-versa.

Étape 3 : Linter l’API

Le linting d’une API est une analyse de son code pour faire remonter des erreurs, warnings et incohérences, à la manière d’un compilateur.

Stoplight propose des style guides de linting par défaut qu’on peut ensuite modifier ou importer. Ces règles seront utilisées pour l’outil de linting intégré basé sur Spectral.

Cela permet de vérifier que la définition de l’API correspond aux bonnes pratiques du marché et aux méthodes spécifiques à l’entreprise.

La configuration du linting est évidemment modifiable à souhait. On pourra ainsi garantir plus facilement une cohérence accrue entre des API qui auraient été faites par diverses personnes, ainsi que réduire le nombre d’erreurs. D’où finalement une API de meilleure qualité.

Étape 4 : Documenter l’API

La documentation de l’API dans Stoplight est gérée via le composant open source Elements intégré à la plateforme. Suivant la spécification OpenAPI, on pourra facilement créer la documentation des endpoints, des réponses, le tout avec un environnement interactif et non figé.

De plus, Stoplight supporte les fichiers Markdown (dans l’onglet Docs) permettant de documenter l’API davantage. Cela offre la possibilité d’y intégrer du contenu non textuel : tableaux, images, diagrammes Mermaid ou contenu d’autres sites (Twitter, Youtube, Giphy, Spotify, etc.). La documentation n’en sera que plus riche et la découverte de votre API facilitée, d’où une meilleure adoption.

Étape 5 : Tester, sécuriser et déployer l’API

Il est possible de tester l’API à l’aide de fonctionnalités nativement intégrées dans l’outil. Ainsi la vérification de contrat sera t-elle automatique via le cross checking de la spécification Open API.

Stoplight propose une interface à travers laquelle écrire et exécuter des tests pour évaluer la réponse de chaque endpoint et méthode. Il est également possible d’utiliser le module Prism pour simuler les appels, dans un environnement de test minimal intégré.

La plateforme supporte les méthodes d’autorisation OAuth2 et OpenIDConnect. L’outil met à disposition une interface dans laquelle il est ainsi possible de déclarer la modalité de contrôle utilisée, le flow et les paramètres évalués (clé d’API, token, credentials)

Enfin l’outil intègre également l’utilitaire de ligne de commande NPM et permet de pousser les mises à jour d’une API sur l’interface de navigation de Stoplight. L’API sera alors sur le Studio Web.

Étape 6 : Générer du code

Une fois l’API testée et validée, vous pouvez utiliser Stoplight pour générer du code serveur et client à partir de votre définition d’API. En effet la plateforme est équipée d’un générateur de code (stubs serveur, configuration…) supportant plusieurs langages de programmation (notamment Java, JavaScript…).

Les capacités de Stoplight à l’heure de la rédaction de cet article sont cependant plus focalisées sur la documentation et les features de collaboration, et sont plus limitées sur la génération de code que celles d’un Swagger Codegen par exemple.

On peut noter pour conclure que Stoplight est un outil avec une couverture relativement large des fonctionnalités de conception et de construction d’une API. Il supporte également les standards d’implémentation en la matière (norme OpenAPI, flux de sécurisation avec OAuth et OIDC…).

Il répond de manière plus complète à des besoins en amont de conception et de développement. Cependant, il présente des limites. Il offre également une couverture moins importante sur des fonctions plus aval, telles que la publication et le contrôle plus fin d’accès à des ressources exposées par API.

Auteurs : Srikanth & Hugues