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 є виклик, що її надсилає, чи обходиться вона без ключа взагалі і чи може її викликати лише людина, яка ввійшла в консоль;

  • параметри шляху, рядка запиту й заголовків, у кожного — тип і те, чи він обов’язковий;

  • тіло запиту, поле за полем, зокрема поля вкладених об’єктів;

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

Ім’я коду помилки в тексті документа — посилання на його рядок у статті Коди помилок.

Що читати далі