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.

API de IONOS pour développeurs
Gérez vos produits d'hébergement grâce à notre puissante API
  • Enregistrements DNS
  • Administration SSL
  • Documentation API

Présentation d’OpenAPI

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.

Note

En parallèle de la définition API, on voit parfois aussi l’expression « spécification API ». Ce terme désigne une description d’API purement destinée à l’humain.

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 :

# YAML
servers:
- url: https://development.example.com/v1
    description: Development server
- url: https://staging.example.com/v1
    description: Staging server
- url: https://api.example.com/v1
    description: Production server
// JSON
{
    "servers": [
        {
            "url": "https://development.example.com/v1",
            "description": "Development server"
        },
        {
            "url": "https://staging.example.com/v1",
            "description": "Staging server"
        },
        {
            "url": "https://api.example.com/v1",
            "description": "Production server"
        }
    ]
}

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

Quels sont les domaines d’application d’OpenAPI ?

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.

Quels sont les avantages d’OpenAPI ?

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.

Quelles versions d’OpenAPI sont disponibles et comment les différencier ?

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

Version Nom Statut
1.0, août 2011 Spécification Swagger n’est plus utilisée
2.0, septembre 2014 Spécification Swagger > spécification OpenAPI toujours prise en charge
30, juillet 2017 Spécification OpenAPI toujours prise en charge
Image: Versions OpenAPI : différences entre les structures des versions 2.0 et 3.0 d’OpenAPI
Dans l’ensemble, la structure de la spécification OpenAPI a été allégée.

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

Nouveau nom pour l’objet Root

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

# <= 2.0
"swagger": "2.0"
# >= 3.0
"OpenAPI": "3.0.0"

Plusieurs hôtes/serveurs

À 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 :

"servers": [
        {
            "url": "https://{username}.example.com:{port}/{basePath}",
            "description": "The production API server",
            "variables": {
                "username": {
                    "default": "demo",
                    "description": "this value is assigned by the service provider, in this example `example.com`"
                },
                "port": {
                    "enum": [
                        "8443",
                        "443"
                    ],
                    "default": "8443"
                },
                "basePath": {
                    "default": "v2"
                }
            }
        }
    ]

Nouveaux objets composants et référence

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
"components": {
    "schemas": {
        // Schéma du repository
        "repository": {
            "title": "Repository",
            "description": "A git repository",
            "type": "object",
            "properties": {
                "id": {
                    "description": "Unique identifier of the repository",
                    "example": 42,
                    "type": "integer"
                },
                "node_id": {
                    "type": "string",
                    "example": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5"
                },
                "name": {
                    "description": "The name of the repository.",
                    "type": "string",
                    "example": "Team Environment"
                },
                "full_name": {
                    "type": "string",
                    "example": "octocat/Hello-World"
                },
                // Définition de licence
                "license": {
                    "nullable": true,
                    "allOf": [
                        {
                            // Référence à un composant défini en externe
                            "$ref": "#/components/schemas/license-simple"
                        }
                    ]
                },

OpenAPI en pratique : deux exemples

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 v3 REST API

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).

L’API d’exemple Petstore de SwaggerHub

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 ».
Note

La ligne de code commençant par « $ref », avec le commentaire « OpenAIP 3.0+ Component » correspond à une référence à des composants OpenAPI définis et distincts.

# Petstore API Template #
# API Endpoint '/pet'
/pet:
    # HTTP-POST Request
    post:
        tags:
            - pet
        summary: Add a new pet to the store
        operationId: addPet
        # HTTP-Status codes
        responses:
            '405':
                description: Invalid input
        security:
            # Permissions
            - petstore_auth:
                - 'write:pets'
                - 'read:pets'
        requestBody:
            # OpenAPI 3.0+ Component
            $ref: '#/components/requestBodies/Pet'
    # HTTP-PUT Request
    put:
        tags:
            - pet
        summary: Update an existing pet
        operationId: updatePet
        # HTTP-Status codes
        responses:
            '400':
                description: Invalid ID supplied
            '404':
                description: Pet not found
            '405':
                description: Validation exception
        security:
            # Permissions
            - petstore_auth:
                - 'write:pets'
                - 'read:pets'
        requestBody:
            # OpenAPI 3.0+ Component
            $ref: '#/components/requestBodies/Pet'
En résumé

OpenAPI s’est imposé comme format de description libre et indépendant pour les services API. Dans un avenir proche, il faut s’attendre à ce qu’il devienne une norme largement répandue pour créer des API REST.

Cet article vous a-t-il été utile ?
Aller au menu principal