slen.ai
Начать

Документ OpenAPI, по которому собран этот справочник

Что содержит документ OpenAPI для Slen API, как из него собраны страницы этого раздела и как читать страницу операции.

2 мин чтения

Slen API описан одним документом OpenAPI: каждая операция, её параметры, поля её запроса и ответов, коды ошибок. Страницы этого раздела нарисованы по этому документу. Эта страница говорит, что содержит документ, что из него показывают страницы и как читать страницу операции.

Документ

  • Документ следует OpenAPI 3.1. Он описывает версию API 1.0 — ту, которую показывает значок рядом с названием этого раздела, и /v1 в начале каждого пути.

  • Его первый сервер — базовый адрес из статьи Обзор, и каждый путь документа задан относительно него.

  • Операция просит API-ключ в заголовке Authorization — Bearer и ключ, — Аутентификация. Проверки /health и /ready ключа не просят, а несколько операций, которые настраивают рабочее пространство, отвечают только человеку, вошедшему в консоль: API-ключу они отвечают 403 с кодом session_required.

  • Тексты документа — что делает операция, что лежит в поле — написаны по-английски, и этот справочник показывает их по-английски на любом языке.

API не отдаёт копию документа, и этот справочник не предлагает её скачать: страницы этого раздела — его читаемая форма.

Что показывают страницы

Страница ресурса рисует по документу операции одной части API: Клиенты и кредиты, Выполнения и другие страницы ресурсов этого раздела. Кроме документа, страница берёт то, что код Slen говорит о каждом маршруте:

  • разрешение, которое нужно ключу, чтобы вызвать операцию;

  • требует ли операция Idempotency-Key;

  • может ли её вызвать API-ключ или только человек, вошедший в консоль;

  • в каком SDK есть вызов, который её отправляет.

Некоторых операций документа нет ни на одной странице, среди них — канал, который консоль держит открытым к Slen для живых обновлений, операции, которые настраивают рабочее пространство, — организации, проекты, ключи, политики, участники, адреса вебхуков, правила оповещений, — и журнал аудита. Рабочее пространство настраивает консоль, и журнал аудита показывает тоже она.

Внизу страницы, нарисованной по документу, строка говорит, из какой ревизии документа и SDK она собрана. Когда таблица справочника и ответ API расходятся, эта строка говорит, с какой ревизией сравнивать.

Как читать операцию

У операции на странице есть метод и путь, описание того, что она делает, а затем:

  • пометки: разрешение, которое ей нужно, требует ли она Idempotency-Key, в каком SDK есть вызов, который её отправляет, обходится ли она без ключа вообще и может ли её вызвать только человек, вошедший в консоль;

  • параметры пути, строки запроса и заголовков, у каждого — тип и то, обязателен ли он;

  • тело запроса, поле за полем, включая поля вложенных объектов;

  • ответы, по одному на каждый статус, которым отвечает операция: тело и заголовки. Тело отказа — конверт ошибки, Обзор.

Имя кода ошибки в тексте документа — ссылка на его строку в статье Коды ошибок.

Что читать дальше