Qu’est-ce que OpenAPI ?

OpenAPI est une norme de description des interfaces de programmation : Application Programming Interfaces (API). La spécification OpenAPI définit un format de description ouvert et indépendant pour les services API. Plus particulièrement, OpenAPI permet de décrire, développer, tester et documenter des API conformes à l’architecture REST.

La spécification OpenAPI actuelle découle d’un projet antérieur, Swagger. L’entreprise de développement SmartBear a placé les spécifications Swagger existantes sous licence libre et confié leur maintenance et leur développement ultérieur à l’OpenAPI Initiative. Outre SmartBear, l’OpenAPI Initiative rassemble des géants du secteur comme Google, IBM et Microsoft. Le projet est également sous la gouvernance de la fondation Linux.

Pour éviter toute confusion, il convient de faire la différence entre OpenAPI et Swagger. OpenAPI est une spécification, c’est-à-dire une description abstraite qui n’est pas rattachée à une implémentation technique particulière. Jusqu’à sa version 2.0, cette spécification s’appelait encore Swagger, avant de prendre le nom de spécification OpenAPI. Pourtant, les outils déjà mis à disposition par l’entreprise de développement d’origine, SmartBear, sont toujours disponibles sous le nom de Swagger.

OpenAPI permet de décrire une API avec une méthode standardisée. On parle ici d’une « définition API ». Celle-ci est créée dans un format qui peut être lu par une machine. Dans ce cas, on utilise plus spécifiquement les deux formats de langage YAML et JSON.

Sur le plan technique, YAML et JSON présentent très peu de différences, ce qui permet d’automatiser la conversion d’une définition API existante d’un langage à l’autre. Quoi qu’il en soit, YAML offre une structure plus claire et plus facile à lire pour l’œil humain. Voici un exemple d’un même objet Server d’un API, rédigé en YAML puis en JSON :

La spécification OpenAPI définit une gamme de propriétés servant à construire une API particulière. Ces propriétés sont désignées par le terme « objet » (d’après l’anglais « Objects »). Dans la version 3.0.3 actuelle, OpenAPI établit la structure des objets suivants :

• Info Object : version, nom etc. de l’API
• Contact Object : informations de contact du fournisseur de l’API
• License Object : licence sous laquelle l’API propose ses données
• Server Object : nom de l’hôte, structure URL et ports du serveur sur lequel sera interrogée l’API
• Components Object : composants encapsulés qui sont utilisés plusieurs fois dans la définition API
• Paths Object : chemins d’accès relatifs aux points de terminaison de l’API, utilisés avec le Server Object
• Path Item Object : pour les opérations autorisées à prendre un chemin spécifique, comme GET, PUT, POST, DELETE
• Operation Object : définit entre autres les paramètres et les réponses du serveur attendues pour une opération

En général, on utilise OpenAPI pour décrire des API REST selon une méthode uniforme. Comme ces descriptions, c’est-à-dire les définitions API, existent dans un format lisible par des machines, elles permettent de créer différents artefacts virtuels de manière automatisée, comme :

• La documentation API : à partir de la définition API lisible par des machines, on crée de manière automatisée la documentation au format HTML. Celle-ci fait office d’ouvrage de référence pour les développeurs qui accèdent aux services de l’API. Si la définition API change, la documentation est générée à nouveau par souci de cohérence.
• Des connexions dans différents langages de programmation : à l’aide d’outils appropriés, il est possible de générer, à partir de la définition API, une bibliothèque logicielle client adaptée dans un langage de programmation pris en charge. C’est un moyen de faciliter l’accès à l’API aux développeurs d’horizons très variés. La bibliothèque logicielle est naturellement intégrée ; l’accès aux services de l’API se fait ensuite, par exemple, en appelant des fonctions au sein de l’environnement de programmation habituel.
• Des tests : chaque composant d’un logiciel doit être soumis à des tests pour en assurer le bon fonctionnement. À chaque modification du code source, il faut à nouveau tester les composants d’un logiciel. La définition API permet de créer automatiquement ces tests et d’évaluer constamment le bon fonctionnement des composants.

Par souci d’exhaustivité, il faut remarquer ici que toutes les API ne sont pas représentées au format OpenAPI. En revanche, les API REST sont clairement prises en charge.

En général, OpenAPI présente l’avantage de préserver la cohérence entre l’implémentation, la documentation et les tests pendant le développement et la maintenance en continu d’une API. De plus, utiliser la spécification OpenAPI assure une meilleure coordination du développement d’une API entre le back-end et le front-end. Les équipes du back-end ou du front-end peuvent développer et tester des composants de code à partir de la définition API sans devoir attendre l’autre équipe.

Outre ces avantages généraux, OpenAPI a été mise en place en tant que base standardisée pour le développement des API REST. C’est très intéressant, car développer une API REST à la main n’est pas chose aisée. Pourtant, les API REST présentent quelques avantages, comme celui de fonctionner sur HTTP/S, système pour lequel les ports de pare-feu sont toujours ouverts.

Utiliser OpenAPI présente aussi les avantages suivants :

• Définir des API HTTP sans dépendre d’un langage de programmation particulier ;
• Générer du code serveur pour une API définie en OpenAPI ;
• Générer des bibliothèques client pour une API conforme à OpenAPI en plus de 40 langages de programmation ;
• Manipuler une définition OpenAPI avec des outils appropriés ;
• Créer une documentation API interactive ;
• Permettre aux hommes et aux machines de découvrir et comprendre les capacités d’un service sans consulter le code source ni avoir recours à une documentation supplémentaire ;
• Accéder aux services API avec une charge de travail minime à l’implémentation.

À la rédaction de cet article, OpenAPI en est à sa version 3.0.3. Voici un petit aperçu des versions précédentes :

Ci-dessous, découvrez les nouveautés principales apportées par le passage de la version 2.0 à la version 3.0 :

La sortie de la version 3.0 a introduit l’objet OpenAPI pour remplacer l’objet Swagger :

À partir de la version 3.0 d’OpenAPI, une API peut être interrogée depuis plus d’un serveur. Il est également possible d’attribuer des définitions variables à certaines parties du serveur URL. Exemple :

Les nouveaux objets composants et référence apportés par la version 3.0 d’OpenAPI représentent une des nouveautés majeures. Les objets composants permettent de définir davantage d’objets réutilisables au sein de la définition API. Ces composants sont intégrés à la définition API à l’aide du qualificatif spécial $ref.

À l’aide des composants et des références, il est possible de construire une API à partir d’un plus grand nombre de composants réutilisables. Cette propriété améliore la lisibilité et limite la taille du document dans son ensemble. Ci-dessous, retrouvez un exemple tiré de la définition API GitHub officielle :

1. Schéma d’un repository de code GitHub, défini comme objet composant
2. Définition de licence référencée à l’aide d’un composant défini en externe

La spécification OpenAPI et ses outils associés, notamment Swagger, est largement utilisée pour créer des API variées. En voici deux exemples :

GitHub, le service de Git populaire, utilise OpenAPI pour décrire son « GitHub v3 REST API ». La définition API est disponible en repository sur GitHub. À l’aide de ce document, un utilisateur peut comprendre exactement quels services sont proposés par l’API de GitHub et comment structurer les requêtes qui lui seront adressées. Par ailleurs, n’importe qui peut utiliser l’API pour écrire du code adapté à l’aide des bons outils.

Selon GitHub, cette définition API sert à décrire, créer, consommer et visualiser l’API REST. À l’heure où nous écrivons ces lignes, la définition API n’est pas disponible dans son intégralité. Il manque encore quelques champs header, qui seront complétés ultérieurement. Il est également mentionné que plusieurs opérations API possibles peuvent être exécutées via différents chemins, alors que la spécification ne liste qu’un chemin.

Pour des questions de compatibilité, GitHub propose la définition API dans différents formats. On trouve tout d’abord une version dite « bundled » (en paquet). Elle contient les composants introduits avec OpenAPI 3.0 et les références rattachées. En parallèle, GitHub propose une version dite « dereferenced » (déréférencée), dont toutes les références ont été supprimées. En raison des répétitions qui en découlent, la définition API déréférencée est presque trois fois plus volumineuse que celle en paquet. De nombreux outils ne prennent pas encore en charge les références : c’est à ces solutions qu’est destinée la version déréférencée.

Vous pouvez consulter vous-même la définition API. Attention, les fichiers complets représentent plusieurs mégabytes. Pour un fichier texte, cela représente une quantité d’information colossale. Il est impossible d’afficher directement un fichier de cette taille sur GitHub. Vous pouvez cependant cliquer sur le lien suivant pour afficher l’API REST de GitHub dans votre navigateur. Il s’agit de la version bien plus compacte et plus lisible en YAML : GitHub REST API (YAML).

Cette fois, nous vous proposons de découvrir l’API d’exemple à générer sur SwaggerHub. SwaggerHub est une plateforme en ligne pour la conception et le développement d’API REST avec OpenAPI. Vous pouvez y créer un compte gratuitement ; vous devez cependant disposer d’un compte existant sur GitHub.

Une fois connecté à SwaggerHub, vous pouvez créer une nouvelle API. Vous avez la possibilité de vous baser sur un modèle existant. Par exemple, il existe un modèle d’API pour un « Petstore » virtuel, c’est-à-dire une animalerie. L’API Petstore créée avec ce modèle comprend un large éventail d’objets OpenAPI. Vous y retrouverez entre autres :

• Des informations de contact, des conditions d’utilisation, des licences, etc. ;
• Les points de terminaison API et les opérations de chacun de ces points ;
• Les paramètres de saisie et de retour autorisés des opérations ;
• Des informations de sécurité.

On peut en apprendre beaucoup sur le fonctionnement d’OpenAPI en consultant l’API Petstore. Par ailleurs, la définition Petstore est un bon exemple de construction d’une API conforme à REST. Enfin, vous trouverez aussi un exemple de code rédigé à partir de l’API Petstore. Analysons ensemble l’extrait de code suivant :

1. Le code définit le point de terminaison API '/pet'.
2. Avec une requête HTTP-POST, on ajoute un nouvel animal dans le magasin.
3. Si l’on utilise plutôt le verbe HTTP « PUT » sur ce point de terminaison, on peut modifier un animal déjà existant.
4. Différentes réponses du serveur sont définies pour les opérations. Les codes de statut HTTP correspondants apparaissant dans cet exemple comprennent le célèbre 404 « Not Found ». Dans ce cas, pour l’animalerie, celui-ci est modifié en « Pet not found ».