Genesis Arbitrage

Genesis Arbitrage · · 3 мин чтения

OpenAPI

OpenAPI (OpenAPI Specification, OAS) — открытый стандарт машиночитаемого описания HTTP API: какие у сервиса пути и методы, какие параметры они принимают, что возвращают и как передавать ключ. Документ пишут в JSON или YAML; по нему API понимают и люди, и программы без доступа к исходному коду.

Откуда стандарт

Стандарт вырос из Swagger Specification, первая версия которой вышла в 2011 году. В 2015 году Swagger 2.0 передали в OpenAPI Initiative — открытый проект Linux Foundation, и с 2016 года спецификация развивается под именем OpenAPI. Версия 3.0 вышла в 2017 году, 3.1 — в феврале 2021-го, самая новая ветка — 3.2 (спецификация 3.1).

Что описывает документ

Сокращённый фрагмент спецификации Genesis API — операция ставок фандинга и схема ключа:

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

Поля с префиксом x- — расширения стандарта: в x-genesis-plans записаны тарифы, в которые входит операция.

Зачем нужна спецификация

Среди применений стандарт перечисляет генерацию документации, генерацию клиентов и серверов на разных языках и тесты. Для ИИ-агентов спецификация — готовый набор инструментов: операция с operationId, описанием и схемой параметров переносится в инструмент для вызова функций или MCP-сервера.

OpenAPI у Genesis API

Спецификация Genesis API лежит по адресу genesisarbitrage.com/openapi.json: OpenAPI 3.1, 37 операций, ключ в заголовке X-API-Key (аутентификация). Её находят и автоматически: каталог /.well-known/api-catalog на genesisarbitrage.com по стандарту RFC 9727 ссылается на неё связью service-desc. Как подключить спецификацию к агенту — в инструкции Genesis API для ИИ-агентов.

Смотрите также: REST API, JSON, эндпоинт, данные крипторынка для ИИ-агентов.

Вопросы и ответы

Swagger и OpenAPI — одно и то же?

Это один стандарт под разными именами: Swagger Specification с 2016 года развивается как OpenAPI. Версия 2.0 вышла ещё как Swagger 2.0, а начиная с 3.0 — как OpenAPI Specification.

Нужен ли SDK, если есть спецификация?

Для Genesis API — нет: все запросы — GET с одним заголовком, хватит любого HTTP-клиента. Сгенерировать клиента из спецификации стоит, если вам нужны типизированные методы.