Qu’est-ce qu’OpenAPI ?

Un fichier OpenAPI, également appelé document OpenAPI ou spécification OpenAPI, permet à un développeur de décrire une API. Cette spécification décrit également comment utiliser cette API, y compris les points de terminaison disponibles, les paramètres d’opération, les méthodes d’authentification et d’autres informations. Ces spécifications sont rédigées en YAML ou JSON, et le schéma JSON est utilisé pour décrire les formats de données dans une API.

OpenAPI sert à la fois de documentation et de contrat (dans l’esprit, il décrit ce que doit faire une API, mais n’est pas juridiquement contraignant) entre les consommateurs et les producteurs d’API. Elle sert essentiellement de « source unique de vérité » et fournit les instructions dans un format standardisé.

Cette standardisation simplifie l’utilisation et l’intégration des API. Elle permet aux humains comme aux ordinateurs de comprendre la fonction et la structure d’une API donnée sans avoir accès au code source ni devoir comprendre le fonctionnement interne de l’API. Elle permet également aux développeurs de travailler avec une API, quelle que soit la langue dans laquelle elle a été écrite.

OpenAPI automatise la documentation interactive et à jour, en éliminant certains travaux de documentation répétitifs et en veillant à ce que la documentation reste à jour. OpenAPI permet également la génération de code pour les SDK clients et la génération automatique d’autres codes types à partir de la spécification, réduisant ainsi les erreurs humaines et minimisant encore le workload des développeurs.

Les outils qui utilisent des spécifications OpenAPI, notamment SwaggerUI, peuvent restituer une spécification API dans une interface interactive. Cette interface permet non seulement de visualiser la spécification, mais aussi d’effectuer des appels API réels, directement à partir du navigateur ou du service web, à des fins de test et de validation.

En standardisant la description des API REST, OpenAPI aide à améliorer l’interopérabilité et les outils, et à soutenir les opérations tout au long du cycle de vie de l’API. Une spécification solide et bien maintenue peut être un outil fondamental pour mettre en œuvre une stratégie API complète, soutenant l’Intégration, la collaboration, la prévention des erreurs et la gestion des API.

La spécification complète est disponible sur GitHub.

En tant que norme du secteur de facto, OpenAPI fournit un document sécurisé, automatisé et largement compris pour le développement d’API.

OpenAPI a été initialement créée par le développeur Tony Tam et publiée pour la première fois en 2011 sous le nom de Swagger. À l’époque, les spécifications API étaient souvent des documents statiques qui nécessitaient une mise à jour fastidieuse et qui étaient souvent obsolètes. La spécification Swagger incluait plusieurs innovations en matière de développement d’API, notamment un bouton « Essayer » pour tester les appels API en direct et en temps réel.

Swagger a fait de la documentation un point central de son existence. Il permet aux développeurs d’ajouter des annotations, semblables à des notes adhésives, à leur code source. Swagger peut lire ces annotations et mettre à jour la documentation automatiquement, garantissant ainsi qu’elle reste à jour sans travail de mise à jour fastidieux et répétitif. Swagger a également introduit un format pour décrire des API en JSON lisible par machine, ce qui le rendait indépendant du langage : quel que soit le langage d’un élément back-end, Swagger génère un fichier JSON universel.

Swagger a été acquis par SmartBear Software en 2015, a été renommé OpenAPI peu après et a été donné à la nouvelle initiative OpenAPI (OAI), sous l’égide de la Linux Foundation. La version actuelle est OpenAPI 3.1.

La spécification OpenAPI est un document standardisé, lisible par l’homme et la machine, qui définit la structure et la syntaxe de l’API. Tous les documents OpenAPI incluent certains composants et respectent la même structure de base, mais certaines spécifications contiennent plus d’informations que d’autres. Au minimum, une spécification doit inclure les champsopenAPI etinfo , et au moins un champpath component ou webhook .¹

openAPI : Notes sur la version OpenAPI utilisée par le document, comme « 3.1.1 »

info : inclut des métadonnées générales sur l’API, telles que le titre et le numéro de version de l’API, une description de l’API, les conditions de service et les coordonnées. 

serveurs : une liste des URL de base où l’API est accessible (qui peut inclure à la fois les environnements de transfert et de production). Cette liste inclut des variables pour les hôtes spécifiques à l’environnement.

chemins : décrit les chemins et les méthodes HTTP associées (ou opérations, par exemple GET, PUT, POST), ainsi que les paramètres, les corps de requête et les réponses pour chaque élément de chemin.

composants : liste des objets réutilisables tels que les schémas de données, les paramètres, les réponses, les en-têtes et les définitions de sécurité. Ces objets peuvent être référencés tout au long du document. Les composants sont référencés, tout simplement, par $ref. Cette stratégie permet de rationaliser au maximum la conception de l’API. 

sécurité : indique les schémas de sécurité et les mécanismes d’authentification utilisés par l’API, tels que les clés OAuth ou API. Il permet également l’application de schémas de sécurité à l’échelle mondiale ou par opération.

tags : liste détaillée des balises utilisées pour organiser les opérations. L’utilisation de balises peut contribuer à améliorer la clarté des documents (par exemple, « Utilisateurs » ou « Commandes »).

documentation externe : liens vers les guides, les documents d’intégration et autres documentations pour l’API

webhooks : décrit les appels entrants que l’API reçoit. 

OpenAPI fournit une source d’information unique pour les développeurs et les consommateurs d’API, et offre des fonctionnalités qui ajoutent de la valeur et de l’efficacité aux projets d’API.

OpenAPI a été initialement créée en mettant l’accent sur la documentation des API REST, et cet objectif reste au cœur de nos préoccupations aujourd’hui. La documentation est normalisée, interactive, mise à jour en temps réel et fournit un contrat avec une source unique de vérité.

Il existe différents outils pour lire les documents OpenAPI et exporter le code. L’un de ces outils est Swagger Codegen, qui lit les documents écrits selon la spécification OpenAPI. Swagger Codegen peut alors produire des kits de développement logiciel (SDK) pour le code client de l’API, du code côté serveur (stubs) et des pages web lisibles par l’homme avec une documentation à jour.

L’une des fonctionnalités les plus innovantes d’OpenAPI reste le bouton « Essayer », qui favorise les tests et les validations en temps réel directement depuis un navigateur. Swagger UI, un outil open source gratuit, permet une interface visuelle dans laquelle un développeur peut envoyer des demandes réelles pour s’assurer qu’elles répondent comme il le souhaite. Cet outil permet de vérifier instantanément le fonctionnement d’une requête.

OpenAPI est couramment utilisée avec les plateformes d’intégration en tant que service, ou iPaaS.

Les plateformes iPaaS utilisent les spécifications OpenAPI pour comprendre et connecter différentes applications dans un écosystème informatique. Lorsque les applications exposent les spécifications OpenAPI qui décrivent leurs API, les plateformes iPaaS peuvent utiliser ces informations pour découvrir automatiquement les points de terminaison, les méthodes d’authentification et les structures de données. Cette stratégie accélère la création d’intégrations, comme la connexion d’une plateforme e-commerce à un logiciel de comptabilité.

OpenAPI permet également aux développeurs front-end et back-end de travailler en parallèle. Il est préférable de travailler en parallèle plutôt que, comme c’est parfois le cas, d’obliger l’équipe front-end à attendre que l’équipe back-end ait mis en place sa base de données et l’ait exécutée. Avec un contrat OpenAPI, l’équipe front-end peut créer un serveur API fictif qui se comporte comme un serveur réel, ce qui permet d’optimiser les tests avant que le développement en back-end ne soit terminé. 

La gouvernance des API, c’est-à-dire les normes, politiques et pratiques qui guident la manière dont une entreprise développe et utilise les API, est essentielle pour garantir que les API fonctionnent de manière fluide, cohérente et sans répétitions inutiles. Comme OpenAPI fait office de contrat entre développeurs, la gouvernance et la sécurité peuvent être intégrées dès le départ.

Prenons par exemple les passerelles API, qui gèrent des tâches comme le routage du trafic, la surveillance et la limitation de débit. Les passerelles API peuvent généralement exploiter les spécifications OpenAPI et appliquer les limites de trafic ou d’autres mesures de sécurité définies dans la spécification.

Il en va de même pour les règles de sécurité. Une spécification OpenAPI permet aux développeurs de déclarer des exigences de sécurité (telles que l’utilisation d’OAuth 2.0 et de clés API), et ces exigences peuvent être appliquées en aval (par une passerelle, par exemple).  La description des fonctionnalités de sécurité dans un contrat d’API permet de s’assurer que les développeurs ne mettent pas en place des schémas de sécurité non pris en charge.

OpenAPI peut renforcer la gestion des API, le processus évolutif de création, de publication et de gestion des connexions API, de plusieurs manières. Par exemple, les spécifications OpenAPI étant lisibles par les machines et standardisées, les logiciels de catalogue et de portail peuvent automatiquement les indexer. Cette normalisation facilite la recherche et la compréhension des API au sein d’une entreprise. Cette visibilité permet également d’empêcher les équipes de créer des API dupliquées sans le savoir.

OpenAPI favorise également une gestion et une gouvernance cohérentes en rendant les normes organisationnelles explicites et applicables. Les équipes peuvent définir les exigences, telles que les conventions de version, les formats de réponse aux erreurs ou les modèles de dénomination, directement dans ou à côté des spécifications. Comme ces attentes sont documentées dans un format standardisé, elles peuvent être automatiquement validées par rapport aux nouvelles API au fur et à mesure de leur ajout. Cette validation réduit le recours à la révision manuelle et permet de garantir la cohérence des API à mesure que le portefeuille de l’entreprise s’agrandit.