Genesis Arbitrage

Genesis Arbitrage · · 3 min de leitura

OpenAPI

OpenAPI (OpenAPI Specification, OAS) é o padrão aberto para descrever uma API HTTP de forma legível por máquinas: quais caminhos e métodos um serviço tem, que parâmetros eles aceitam, o que devolvem e como passar a chave. O documento é escrito em JSON ou YAML, e tanto pessoas quanto programas conseguem entender a API a partir dele, sem acesso ao código-fonte.

De onde veio o padrão

O padrão nasceu da Swagger Specification, lançada pela primeira vez em 2011. Em 2015, o Swagger 2.0 foi doado à OpenAPI Initiative, um projeto aberto da Linux Foundation, e desde 2016 a especificação é desenvolvida como OpenAPI. A versão 3.0 saiu em 2017 e a 3.1 em fevereiro de 2021; a linha mais recente é a 3.2 (a especificação 3.1).

O que o documento descreve

Um trecho resumido da spec da Genesis API, a operação de taxas de funding e o esquema da chave:

{
  "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" }
    }
  }
}

Campos com prefixo x- são extensões da especificação: x-genesis-plans lista os planos que incluem a operação.

Para que serve uma spec

Entre seus usos, o padrão cita geração de documentação, geração de clientes e servidores em várias linguagens e testes. Para agentes de IA, uma spec é um conjunto de ferramentas pronto: uma operação com operationId, descrição e schema de parâmetros vira uma ferramenta para function calling ou um servidor MCP.

OpenAPI na Genesis API

A spec da Genesis API fica em genesisarbitrage.com/openapi.json: OpenAPI 3.1, 37 operações, a chave no cabeçalho X-API-Key (autenticação). Ela também pode ser descoberta automaticamente: o arquivo /.well-known/api-catalog de genesisarbitrage.com, definido pela RFC 9727, aponta para ela com um link service-desc. Como conectar a spec a um agente está em Genesis API para agentes de IA.

Veja também: REST API, JSON, endpoint de API, dados de mercado cripto para agentes de IA.

Perguntas e respostas

Swagger e OpenAPI são a mesma coisa?

São um único padrão com dois nomes: a Swagger Specification é desenvolvida como OpenAPI desde 2016. A versão 2.0 ainda saiu como Swagger 2.0, e a partir da 3.0 é publicada como OpenAPI Specification.

Preciso de um SDK se existe uma spec?

Não para a Genesis API: cada requisição é um GET com um único cabeçalho, então qualquer cliente HTTP serve. Gerar um cliente a partir da spec faz sentido se você quer métodos tipados.