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 IONOS gratuite
Utilisez l’API de IONOS sans frais supplémentaires pour récupérer ou mettre à jour les données relatives à vos domaines, DNS et SSL.
Enregistrements DNSAdministration SSLDocumentation APIPour é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.
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 :
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 :
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 :
À 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 |
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 :
# <= 2.0
"swagger": "2.0"
# >= 3.0
"OpenAPI": "3.0.0"À 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"
}
}
}
]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 :
"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"
}
]
},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 :
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 :
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'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.
L'intégration continue permet d’améliorer le travail de développement logiciel : moins d'erreurs et une intégration plus efficace et continue. Elle nécessite toutefois un outil simple, mais néanmoins complet. Ce tutoriel vous présente Jenkins, un logiciel qui facilite le travail, avec des builds automatiques et des pipelines personnalisés. Grâce à lui, vous ne vous sentirez pas livré à vous-même....
Les développeurs doivent considérer un certain nombre d’éléments : l’application doit être fonctionnelle et ergonomique, mais elle doit également disposer d’une performance optimale et être exempte d’erreurs de programmation. Finalement, le produit doit pouvoir fonctionner sur les plates-formes et les appareils ciblés. En quoi des Software Development Kits (SDK) peuvent-ils aider à atteindre ces...
Dans le développement logiciel, le terme « Cloud Native » est sur toutes les lèvres depuis un certain temps. Mais qu’est-ce que le Cloud Native et comment est-il appliqué avec succès ? La méthode de développement agile vise à développer des applications qui s’intègrent parfaitement dans une infrastructure Cloud. Apprenez-en davantage sur les caractéristiques et les avantages de l’architecture...
Si vous êtes déjà expert en codage en CSS et que vous cherchez un framework particulièrement flexible et individuel, Tailwind CSS est une bonne option. Cette solution destinée aux professionnels simplifie le travail et offre un vaste éventail d’options de design. Lisez cet article dédié pour en savoir plus sur ce framework et pourquoi les débutants devraient plutôt utiliser une alternative à...
Offrez un service performant et fiable à vos clients avec l'hébergement web de IONOS.
Voir les packs
