Genesis Arbitrage

Genesis Arbitrage · · 3 min de lectura

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

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.