Проект API
Это каталог спроектированного, а не работающего. Здесь описан весь замысел API — 226 операций, — и честно помечено, чему верить.
Рабочая часть живёт в соседнем разделе API: там первый срез, который сейчас в разработке, быстрый старт и справочные страницы. Граница между разделами описана в Составе среза.
Что из этого следует для читателя каталога:
- Оценить, закроет ли платформа задачу, — можно. Состав операций, модель прав, формат, лимиты и устройство вебхуков спроектированы и описаны.
- Писать интеграцию — нельзя. Из 226 операций у 60 адрес выведен из сокращённой записи спецификации, а не написан в ней прямо: он может оказаться другим. Такие операции помечены на своих страницах словами «адрес предположительный».
- Тел запросов и состава полей в ответах здесь нет. По ADR-057 они выводятся из zod-валидаторов; валидаторов у нереализованных операций не существует. Вместо правдоподобного примера стоит пометка «чего здесь нет» — придуманный пример скопируют в чужой код, и он будет неверным.
Страницы раздела #
| Страница | Что там |
|---|---|
| Каталог ресурсов | Все 226 операций по девяти областям, с путями, параметрами и curl |
| Каталог событий | 82 события по группам |
Адреса каталога остаются под /api/reference/ — они были опубликованы раньше
разделения, а адреса мы не ломаем. В навигации и в карте сайта каталог живёт здесь.
Машинная спецификация — openapi.draft.json #
Черновик всего замысла: /openapi.draft.json. «Draft» в имени не для красоты —
у документа стоит признак x-lms-provisional: true, у выведенных адресов —
x-lms-shorthand, у операций без описанных тел — x-lms-unspecified. Проверять
эти признаки — самый дешёвый способ не построить интеграцию на несуществующем.
Конвенциональное имя /openapi.json занято не будет, пока по нему не начнёт
отдаваться спецификация работающих операций — она появится вместе с первым
срезом, из валидаторов.
Как операции переезжают в «API» #
По мере реализации, а не разом:
- операция реализуется в коде — у неё появляется валидатор;
- спецификация рабочих операций собирается из валидаторов в
/openapi.json; - операция появляется в каталоге раздела «API» и исчезает из черновика;
- пометки «адрес предположительный» у неё больше нет — адрес либо подтвердился, либо изменился, и это видно;
- описания, написанные проектированием (§19 спецификации), переезжают в код.
Адреса страниц при этом не меняются — на них можно ссылаться уже сейчас.