Partager:
){kind=small}
Alyssa is a writer and editor specializing in technology and the software development space. She lives in central California with her husband, kids, and three rescue dogs.
Développement basé sur l'OpenAPI chez Nexmo
Temps de lecture : 4 minutes
Chez Nexmo, nous avons adopté un processus de développement basé sur l'OpenAPI. Voici pourquoi.
L'histoire nous a appris que le développement de logiciels étouffe sous le poids de spécifications surchargées.
Andy Hunt, co-auteur du Manifeste Agile, raconte l'histoire d'un projet sur lequel il a travaillé dans les années 1990. Après deux ans et demi et plusieurs millions de dollars, l'architecte du projet avait produit une salle pleine de diagrammes UML, mais pas une seule ligne de code n'avait été déployée.
Aujourd'hui, nous équilibrons soigneusement le besoin de spécifications initiales avec la compréhension du fait que ce n'est souvent qu'en écrivant le code lui-même que nous découvrons la véritable nature du problème que nous résolvons.
Il s'avère cependant que l'équilibre entre les spécifications et la découverte est différent pour les API publiques de ce qu'il est lorsque nous construisons d'autres types de logiciels. Chez Nexmo, cela nous a amenés à modifier notre façon de développer de nouvelles API : la première chose que nous faisons lorsque nous développons un nouveau service est de créer une spécification OpenAPI. Cela nous permet de bénéficier de l'expérience des développeurs, de la lisibilité humaine par rapport à la machine, de l'automatisation, et bien plus encore.
Les API sont des contrats publics. Lorsque nous construisons et lançons quelque chose comme notre Messages APInous concluons un accord avec nos clients : si vous faites l'appel API X avec les données Y, notre plateforme fera Z.
La création d'une API publique revient donc essentiellement à créer une norme. Pensez au SVG. Il s'agit d'une norme pour les graphiques vectoriels. La norme et les diverses implémentations de cette norme existent en tant que choses distinctes. Si j'écris une bibliothèque qui génère des fichiers SVG, je ne devrais pas avoir à me soucier des détails de l'implémentation du logiciel qui lira ensuite ce fichier.
Trop souvent, les API sont façonnées par la mise en œuvre sous-jacente - ce que Joel Spolsky appelle des abstractions fuyantes-ou par des décisions de conception prises à la volée. Commencer par créer une spécification OpenAPI signifie que nous pouvons prendre des décisions de conception intentionnelles qui ne sont pas liées aux détails de ce qui se passe en dessous. Il en résulte une expérience cohérente et intuitive pour les développeurs.
Un avantage inattendu est que la création de spécifications OpenAPI permet de découvrir d'éventuels problèmes d'utilisation. Nous avons constaté que s'il est difficile de modéliser une API dans une spécification OpenAPI, cela tend à signifier que l'API elle-même sera difficile à utiliser. Cela nous a poussés à repenser certaines conceptions d'API moins optimales qui auraient pu être mises en production.
Taylor Barnett de Stoplight.io décrit les spécifications OpenAPI comme "un contrat de développement, un pont entre les équipes." Même si ce sont les humains qui écrivent le code, les API servent explicitement d'interfaces entre les machines.
Le développement basé sur les spécifications OpenAPI fait de l'API bien plus qu'une simple interface entre deux bouts de code. Il transforme l'API en une source d'accord entre les personnes. Les rédacteurs techniques peuvent l'utiliser pour lancer les efforts de documentation, les défenseurs des développeurs pour l'expliquer aux développeurs externes, les gestionnaires de produits pour la maintenir comme source de vérité concernant les capacités de l'API.
Comme l'a documenté par Kin Laneles entreprises publient de plus en plus souvent leurs spécifications OpenAPI sur GitHub en tant que déclaration publique de la conception d'une API. Avec un seul document, nous pouvons faire une déclaration lisible par la machine et par l'homme sur la façon dont l'API doit se comporter. À partir de là, les développeurs peuvent voir quel est le comportement attendu et raisonner sur les capacités de l'API.
Les spécifications OpenAPI promettent de permettre toutes sortes d'automatisations. Le potentiel est de pouvoir générer automatiquement des bibliothèques de clients, des points de terminaison fictifs, des tests et de la documentation.
Screenshot of API
Chez Nexmo, nous sommes au début de ce voyage. Aujourd'hui, nous générons automatiquement des documents de référence sur les API et quelques tests. En particulier, nous avons constaté que le fait d'avoir une spécification OpenAPI dès le départ a facilité la création de tests de fumée.
Nos spécifications OpenAPI définissent les entrées et sorties attendues de l'API, y compris les messages d'erreur. Nous pouvons utiliser ces spécifications pour générer automatiquement des tests de fumée qui fournissent des données intentionnellement incorrectes et qui vérifient ensuite que le message d'erreur attendu est renvoyé.
En fin de compte, le plus grand avantage est qu'en commençant par une spécification OpenAPI, nous disposons d'une source unique de vérité. Plutôt que d'avoir des conceptions d'API dans différents formats et à différents endroits (wikis, Google Docs, etc.), la spécification fait désormais partie intégrante du processus de développement et est créée à l'aide d'outils de développement standard.
Cette spécification unique nous permet, ainsi qu'à nos collègues, de savoir quand le développement est terminé et de dire aux développeurs externes à quoi s'attendre. Dans un certain sens, la spécification est l'API et la mise en œuvre n'est que cela.
Nous sommes au début de notre voyage OpenAPI-first. Jusqu'à présent, nous avons testé le processus avec deux API, à savoirRedact et Secret Management-mais toutes nos API ont des spécifications OpenAPI complètes et publiques et nous prévoyons de faire passer l'ensemble de notre développement au modèle "spec-first".
D'après notre travail jusqu'à présent, nous sommes certains que cela conduira à des mises en œuvre d'API de meilleure qualité, à un gain de temps et à une meilleure compréhension. Nous sommes impatients de voir comment cela améliorera la qualité des API dans l'ensemble du secteur.