OpenAPI
OpenAPI (OpenAPI Specification, OAS) es el estándar abierto para describir una API HTTP de forma legible por máquinas: qué rutas y métodos tiene un servicio, qué parámetros aceptan, qué devuelven y cómo pasar la clave. El documento se escribe en JSON o YAML, y tanto personas como programas pueden entender la API a partir de él sin acceso al código fuente.
De dónde viene el estándar
El estándar nació de la Swagger Specification, publicada por primera vez en 2011. En 2015 Swagger 2.0 se donó a la OpenAPI Initiative, un proyecto abierto de la Linux Foundation, y desde 2016 la especificación se desarrolla como OpenAPI. La versión 3.0 salió en 2017 y la 3.1 en febrero de 2021; la línea más reciente es la 3.2 (la especificación 3.1).
Qué describe el documento
servers— la URL base de la API;paths— rutas y métodos: cada operación tiene suoperationId, unsummarybreve, parámetros con su ubicación (in: query, path, header) y respuestas por código de estado;components.schemas— esquemas de objetos (en 3.1, basados en JSON Schema 2020-12);components.securitySchemes— autenticación, por ejemplo una clave en un encabezado:type: apiKey,in: header.
Un extracto abreviado de la spec de Genesis API, la operación de tasas de funding y el esquema de la clave:
{
"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" }
}
}
}
Los campos con prefijo x- son extensiones de la especificación: x-genesis-plans enumera los planes que incluyen la operación.
Para qué sirve una spec
Entre sus usos, el estándar menciona generar documentación, generar clientes y servidores en distintos lenguajes y hacer pruebas. Para los agentes de IA una spec es un conjunto de herramientas listo: una operación con operationId, descripción y esquema de parámetros equivale a una herramienta para function calling o un servidor MCP.
OpenAPI en Genesis API
La spec de Genesis API está en genesisarbitrage.com/openapi.json: OpenAPI 3.1, 37 operaciones, la clave en el encabezado X-API-Key (autenticación). También se puede descubrir de forma automática: el archivo /.well-known/api-catalog de genesisarbitrage.com, definido por el RFC 9727, apunta a ella con un enlace service-desc. Cómo conectar la spec a un agente se explica en Genesis API para agentes de IA.
Véase también: REST API, JSON, endpoint de API, datos de mercado cripto para agentes de IA.
Preguntas y respuestas
¿Swagger y OpenAPI son lo mismo?
Son un mismo estándar con dos nombres: la Swagger Specification se desarrolla como OpenAPI desde 2016. La versión 2.0 aún salió como Swagger 2.0, y desde la 3.0 se publica como OpenAPI Specification.
¿Necesito un SDK si hay una spec?
No para Genesis API: cada petición es un GET con un solo encabezado, así que sirve cualquier cliente HTTP. Generar un cliente a partir de la spec tiene sentido si quieres métodos tipados.