OpenAPI
OpenAPI (OpenAPI Specification, OAS) est le standard ouvert pour décrire une API HTTP de façon lisible par machine : quels chemins et méthodes un service propose, quels paramètres ils acceptent, ce qu'ils renvoient et comment transmettre la clé. Le document s'écrit en JSON ou en YAML, et les personnes comme les programmes peuvent comprendre l'API à partir de lui, sans accès au code source.
D'où vient le standard
Le standard est issu de la Swagger Specification, publiée pour la première fois en 2011. En 2015, Swagger 2.0 a été donné à l'OpenAPI Initiative, un projet ouvert de la Linux Foundation, et depuis 2016 la spécification évolue sous le nom OpenAPI. La version 3.0 est sortie en 2017 et la 3.1 en février 2021 ; la ligne la plus récente est la 3.2 (la spécification 3.1).
Ce que décrit le document
servers— l'URL de base de l'API ;paths— chemins et méthodes : chaque opération a sonoperationId, un courtsummary, des paramètres avec leur emplacement (in: query, path, header) et des réponses par code de statut ;components.schemas— schémas d'objets (en 3.1, fondés sur JSON Schema 2020-12) ;components.securitySchemes— authentification, par exemple une clé dans un en-tête :type: apiKey,in: header.
Un extrait abrégé de la spec de Genesis API, l'opération taux de funding et le schéma de la clé :
{
"openapi": "3.1.0",
"servers": [{ "url": "https://api.genesisarbitrage.com/v1" }],
"paths": {
"/funding/rates": {
"get": {
"operationId": "getFundingRates",
"summary": "Funding rates",
"x-genesis-plans": ["trial", "start", "pro", "max"],
"parameters": [
{ "name": "coin", "in": "query", "required": false,
"schema": { "type": "string" } }
]
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": { "type": "apiKey", "in": "header",
"name": "X-API-Key" }
}
}
}
Les champs préfixés par x- sont des extensions de la spécification : x-genesis-plans liste les plans qui incluent l'opération.
À quoi sert une spec
Parmi ses usages, le standard cite la génération de documentation, la génération de clients et de serveurs dans différents langages, et les tests. Pour les agents d'IA, une spec est un jeu d'outils prêt à l'emploi : une opération avec un operationId, une description et un schéma de paramètres correspond à un outil pour le function calling ou un serveur MCP.
OpenAPI dans Genesis API
La spec de Genesis API se trouve à l'adresse genesisarbitrage.com/openapi.json : OpenAPI 3.1, 37 opérations, clé dans l'en-tête X-API-Key (authentification). Elle se découvre aussi automatiquement : le fichier /.well-known/api-catalog de genesisarbitrage.com, défini par la RFC 9727, y renvoie par un lien service-desc. La connexion de la spec à un agent est expliquée dans Genesis API pour les agents d'IA.
Voir aussi : REST API, JSON, endpoint d'API, données de marché crypto pour agents d'IA.
Questions et réponses
Swagger et OpenAPI, est-ce la même chose ?
C'est un seul standard sous deux noms : la Swagger Specification évolue sous le nom OpenAPI depuis 2016. La version 2.0 est encore sortie sous le nom Swagger 2.0, et depuis la 3.0 elle est publiée comme OpenAPI Specification.
Faut-il un SDK quand on a une spec ?
Pas pour Genesis API : chaque requête est un GET avec un seul en-tête, donc n'importe quel client HTTP convient. Générer un client à partir de la spec a du sens si vous voulez des méthodes typées.