Qu’est-ce que OpenAPI ?

OpenAPI est une norme de des­crip­tion des in­ter­faces de pro­gram­ma­tion : Ap­pli­ca­tion Pro­gram­ming In­ter­faces (API). La spé­ci­fi­ca­tion OpenAPI définit un format de des­crip­tion ouvert et in­dé­pen­dant pour les services API. Plus par­ti­cu­liè­re­ment, OpenAPI permet de décrire, dé­ve­lop­per, tester et do­cu­men­ter des API conformes à l’ar­chi­tec­ture REST.

La spé­ci­fi­ca­tion OpenAPI actuelle découle d’un projet antérieur, Swagger. L’en­tre­prise de dé­ve­lop­pe­ment SmartBear a placé les spé­ci­fi­ca­tions Swagger exis­tantes sous licence libre et confié leur main­te­nance et leur dé­ve­lop­pe­ment ultérieur à l’OpenAPI Ini­tia­tive. Outre SmartBear, l’OpenAPI Ini­tia­tive rassemble des géants du secteur comme Google, IBM et Microsoft. Le projet est également sous la gou­ver­nance de la fondation Linux.

Pour éviter toute confusion, il convient de faire la dif­fé­rence entre OpenAPI et Swagger. OpenAPI est une spé­ci­fi­ca­tion, c’est-à-dire une des­crip­tion abstraite qui n’est pas rattachée à une im­plé­men­ta­tion technique par­ti­cu­lière. Jusqu’à sa version 2.0, cette spé­ci­fi­ca­tion s’appelait encore Swagger, avant de prendre le nom de spé­ci­fi­ca­tion OpenAPI. Pourtant, les outils déjà mis à dis­po­si­tion par l’en­tre­prise de dé­ve­lop­pe­ment d’origine, SmartBear, sont toujours dis­po­nibles sous le nom de Swagger.

OpenAPI permet de décrire une API avec une méthode stan­dar­di­sée. On parle ici d’une « dé­fi­ni­tion API ». Celle-ci est créée dans un format qui peut être lu par une machine. Dans ce cas, on utilise plus spé­ci­fi­que­ment les deux formats de langage YAML et JSON.

Sur le plan technique, YAML et JSON pré­sen­tent très peu de dif­fé­rences, ce qui permet d’au­to­ma­ti­ser la con­ver­sion d’une dé­fi­ni­tion 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é­ci­fi­ca­tion OpenAPI définit une gamme de pro­prié­tés servant à cons­truire une API par­ti­cu­lière. Ces pro­prié­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 : in­for­ma­tions de contact du four­nis­seur 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 in­ter­ro­gée l’API
• Com­po­nents Object : com­po­sants en­cap­su­lés qui sont utilisés plusieurs fois dans la dé­fi­ni­tion API
• Paths Object : chemins d’accès relatifs aux points de ter­mi­nai­son de l’API, utilisés avec le Server Object
• Path Item Object : pour les opé­ra­tions au­to­ri­sées à prendre un chemin spé­ci­fique, comme GET, PUT, POST, DELETE
• Operation Object : définit entre autres les pa­ra­mè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 des­crip­tions, c’est-à-dire les dé­fi­ni­tions API, existent dans un format lisible par des machines, elles per­met­tent de créer dif­fé­rents artefacts virtuels de manière au­to­ma­ti­sée, comme :

• La do­cu­men­ta­tion API : à partir de la dé­fi­ni­tion API lisible par des machines, on crée de manière au­to­ma­ti­sée la do­cu­men­ta­tion au format HTML. Celle-ci fait office d’ouvrage de référence pour les dé­ve­lop­peurs qui accèdent aux services de l’API. Si la dé­fi­ni­tion API change, la do­cu­men­ta­tion est générée à nouveau par souci de cohérence.
• Des con­nexions dans dif­fé­rents langages de pro­gram­ma­tion : à l’aide d’outils ap­pro­priés, il est possible de générer, à partir de la dé­fi­ni­tion API, une bi­blio­thèque lo­gi­cielle client adaptée dans un langage de pro­gram­ma­tion pris en charge. C’est un moyen de faciliter l’accès à l’API aux dé­ve­lop­peurs d’horizons très variés. La bi­blio­thèque lo­gi­cielle est na­tu­rel­le­ment intégrée ; l’accès aux services de l’API se fait ensuite, par exemple, en appelant des fonctions au sein de l’en­vi­ron­ne­ment de pro­gram­ma­tion habituel.
• Des tests : chaque composant d’un logiciel doit être soumis à des tests pour en assurer le bon fonc­tion­ne­ment. À chaque mo­di­fi­ca­tion du code source, il faut à nouveau tester les com­po­sants d’un logiciel. La dé­fi­ni­tion API permet de créer au­to­ma­ti­que­ment ces tests et d’évaluer cons­tam­ment le bon fonc­tion­ne­ment des com­po­sants.

Par souci d’ex­haus­ti­vité, il faut remarquer ici que toutes les API ne sont pas re­pré­sen­tées au format OpenAPI. En revanche, les API REST sont clai­re­ment prises en charge.

En général, OpenAPI présente l’avantage de préserver la cohérence entre l’im­plé­men­ta­tion, la do­cu­men­ta­tion et les tests pendant le dé­ve­lop­pe­ment et la main­te­nance en continu d’une API. De plus, utiliser la spé­ci­fi­ca­tion OpenAPI assure une meilleure coor­di­na­tion du dé­ve­lop­pe­ment d’une API entre le back-end et le front-end. Les équipes du back-end ou du front-end peuvent dé­ve­lop­per et tester des com­po­sants de code à partir de la dé­fi­ni­tion API sans devoir attendre l’autre équipe.

Outre ces avantages généraux, OpenAPI a été mise en place en tant que base stan­dar­di­sée pour le dé­ve­lop­pe­ment des API REST. C’est très in­té­res­sant, car dé­ve­lop­per une API REST à la main n’est pas chose aisée. Pourtant, les API REST pré­sen­tent quelques avantages, comme celui de fonc­tion­ner 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 pro­gram­ma­tion par­ti­cu­lier ;
• Générer du code serveur pour une API définie en OpenAPI ;
• Générer des bi­blio­thèques client pour une API conforme à OpenAPI en plus de 40 langages de pro­gram­ma­tion ;
• Manipuler une dé­fi­ni­tion OpenAPI avec des outils ap­pro­priés ;
• Créer une do­cu­men­ta­tion API in­te­rac­tive ;
• Permettre aux hommes et aux machines de découvrir et com­prendre les capacités d’un service sans consulter le code source ni avoir recours à une do­cu­men­ta­tion sup­plé­men­taire ;
• Accéder aux services API avec une charge de travail minime à l’im­plé­men­ta­tion.

À 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 nou­veau­tés prin­ci­pales 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 in­ter­ro­gée depuis plus d’un serveur. Il est également possible d’attribuer des dé­fi­ni­tions variables à certaines parties du serveur URL. Exemple :

Les nouveaux objets com­po­sants et référence apportés par la version 3.0 d’OpenAPI re­pré­sen­tent une des nou­veau­tés majeures. Les objets com­po­sants per­met­tent de définir davantage d’objets réu­ti­li­sables au sein de la dé­fi­ni­tion API. Ces com­po­sants sont intégrés à la dé­fi­ni­tion API à l’aide du qua­li­fi­ca­tif spécial $ref.

À l’aide des com­po­sants et des ré­fé­rences, il est possible de cons­truire une API à partir d’un plus grand nombre de com­po­sants réu­ti­li­sables. Cette propriété améliore la li­si­bi­lité et limite la taille du document dans son ensemble. Ci-dessous, retrouvez un exemple tiré de la dé­fi­ni­tion API GitHub of­fi­cielle :

1. Schéma d’un re­po­si­tory de code GitHub, défini comme objet composant
2. Dé­fi­ni­tion de licence ré­fé­ren­cée à l’aide d’un composant défini en externe

La spé­ci­fi­ca­tion 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é­fi­ni­tion API est dis­po­nible en re­po­si­tory sur GitHub. À l’aide de ce document, un uti­li­sa­teur peut com­prendre exac­te­ment quels services sont proposés par l’API de GitHub et comment struc­tu­rer 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é­fi­ni­tion API sert à décrire, créer, consommer et vi­sua­li­ser l’API REST. À l’heure où nous écrivons ces lignes, la dé­fi­ni­tion API n’est pas dis­po­nible dans son in­té­gra­lité. Il manque encore quelques champs header, qui seront complétés ul­té­rieu­re­ment. Il est également mentionné que plusieurs opé­ra­tions API possibles peuvent être exécutées via dif­fé­rents chemins, alors que la spé­ci­fi­ca­tion ne liste qu’un chemin.

Pour des questions de com­pa­ti­bi­lité, GitHub propose la dé­fi­ni­tion API dans dif­fé­rents formats. On trouve tout d’abord une version dite « bundled » (en paquet). Elle contient les com­po­sants in­tro­duits avec OpenAPI 3.0 et les ré­fé­rences rat­ta­chées. En parallèle, GitHub propose une version dite « de­re­fe­ren­ced » (dé­ré­fé­ren­cée), dont toutes les ré­fé­rences ont été sup­pri­mées. En raison des ré­pé­ti­tions qui en découlent, la dé­fi­ni­tion API dé­ré­fé­ren­cée est presque trois fois plus vo­lu­mi­neuse 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é­ren­cée.

Vous pouvez consulter vous-même la dé­fi­ni­tion API. Attention, les fichiers complets re­pré­sen­tent plusieurs mégabytes. Pour un fichier texte, cela re­pré­sente une quantité d’in­for­ma­tion colossale. Il est im­pos­sible d’afficher di­rec­te­ment un fichier de cette taille sur GitHub. Vous pouvez cependant cliquer sur le lien suivant pour afficher l’API REST de GitHub dans votre na­vi­ga­teur. 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 Swag­ge­rHub. Swag­ge­rHub est une pla­te­forme en ligne pour la con­cep­tion et le dé­ve­lop­pe­ment d’API REST avec OpenAPI. Vous pouvez y créer un compte gra­tui­te­ment ; vous devez cependant disposer d’un compte existant sur GitHub.

Une fois connecté à Swag­ge­rHub, vous pouvez créer une nouvelle API. Vous avez la pos­si­bi­lité 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 ani­ma­le­rie. L’API Petstore créée avec ce modèle comprend un large éventail d’objets OpenAPI. Vous y re­trou­ve­rez entre autres :

• Des in­for­ma­tions de contact, des con­di­tions d’uti­li­sa­tion, des licences, etc. ;
• Les points de ter­mi­nai­son API et les opé­ra­tions de chacun de ces points ;
• Les pa­ra­mètres de saisie et de retour autorisés des opé­ra­tions ;
• Des in­for­ma­tions de sécurité.

On peut en apprendre beaucoup sur le fonc­tion­ne­ment d’OpenAPI en con­sul­tant l’API Petstore. Par ailleurs, la dé­fi­ni­tion Petstore est un bon exemple de cons­truc­tion 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 ter­mi­nai­son 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 ter­mi­nai­son, on peut modifier un animal déjà existant.
4. Dif­fé­rentes réponses du serveur sont définies pour les opé­ra­tions. Les codes de statut HTTP cor­res­pon­dants ap­pa­rais­sant dans cet exemple com­pren­nent le célèbre 404 « Not Found ». Dans ce cas, pour l’ani­ma­le­rie, celui-ci est modifié en « Pet not found ».