Проект API

Это проектная спецификация. Работающего API в продукте ещё нет.

Маршрутов /v1/* в коде ноль. Реализация назначена после среза 2 (ADR-054). Всё, что в этом разделе, описывает замысел, а не поведение работающей системы.

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

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

Машинная спецификация лежит на /openapi.draft.json. Адрес /openapi.json не занят намеренно: это конвенция, и агент, скачавший файл по такому адресу, обоснованно считает, что перед ним рабочее API.

Что уже описано по-настоящему #

Не всё в этом разделе — черновик. Три вещи описаны полностью и не изменятся:

• Формат ошибки — тело, коды, request_id. Задан в спецификации целиком.
• Формат конверта вебхука — один на все события, включая previous и related. Это принципиальное решение, а не деталь: у GetCourse три несовместимые схемы, и единый обработчик там написать нельзя.
• Каталог событий — 82 события. Имена событий и есть контракт; меняться будет состав data.object, а не имена.

Принцип паритета #

Всё, что можно сделать руками в интерфейсе, можно сделать по API. Интерфейс не имеет привилегированного доступа: он вызывает те же сервисы, что и API-роут. Операция, доступная только из админки, — это ошибка архитектуры, а не особенность.

Отсюда и объём: одно API на всё, а не «классическое» и «новое» с разной аутентификацией и разным форматом тела.

Когда это станет настоящим #

Когда появятся маршруты и валидаторы:

1. спецификация начнёт собираться из кода, а не из проектного документа;
2. пометки «адрес предположительный» исчезнут — либо адрес подтвердится, либо изменится;
3. файл переедет с /openapi.draft.json на /openapi.json;
4. раздел будет называться «API».

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