# Проект API

**Это каталог спроектированного, а не работающего.** Здесь описан весь замысел API —
226 операций, — и честно помечено, чему верить.

Рабочая часть живёт в соседнем разделе **[API](/api/)**: там первый срез,
который сейчас в разработке, быстрый старт и справочные страницы. Граница между
разделами описана в [Составе среза](/api/scope/).

Что из этого следует для читателя каталога:

- **Оценить, закроет ли платформа задачу, — можно.** Состав операций, модель прав,
  формат, лимиты и устройство вебхуков спроектированы и описаны.
- **Писать интеграцию — нельзя.** Из 226 операций у 60 адрес выведен из сокращённой
  записи спецификации, а не написан в ней прямо: он может оказаться другим. Такие
  операции помечены на своих страницах словами «адрес предположительный».
- **Тел запросов и состава полей в ответах здесь нет.** По ADR-057 они выводятся
  из zod-валидаторов; валидаторов у нереализованных операций не существует. Вместо
  правдоподобного примера стоит пометка «чего здесь нет» — придуманный пример
  скопируют в чужой код, и он будет неверным.

## Страницы раздела

| Страница | Что там |
|---|---|
| [Каталог ресурсов](/api/reference/) | Все 226 операций по девяти областям, с путями, параметрами и curl |
| [Каталог событий](/api/events/) | 82 события по группам |

Адреса каталога остаются под `/api/reference/` — они были опубликованы раньше
разделения, а адреса мы не ломаем. В навигации и в карте сайта каталог живёт здесь.

## Машинная спецификация — openapi.draft.json

Черновик всего замысла: `/openapi.draft.json`. «Draft» в имени не для красоты —
у документа стоит признак `x-lms-provisional: true`, у выведенных адресов —
`x-lms-shorthand`, у операций без описанных тел — `x-lms-unspecified`. Проверять
эти признаки — самый дешёвый способ не построить интеграцию на несуществующем.

Конвенциональное имя `/openapi.json` занято не будет, пока по нему не начнёт
отдаваться спецификация **работающих** операций — она появится вместе с первым
срезом, из валидаторов.

## Как операции переезжают в «API»

По мере реализации, а не разом:

1. операция реализуется в коде — у неё появляется валидатор;
2. спецификация рабочих операций собирается из валидаторов в `/openapi.json`;
3. операция появляется в каталоге раздела «API» и исчезает из черновика;
4. пометки «адрес предположительный» у неё больше нет — адрес либо подтвердился,
   либо изменился, и это видно;
5. описания, написанные проектированием (§19 спецификации), переезжают в код.

**Адреса страниц при этом не меняются** — на них можно ссылаться уже сейчас.