API

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

Состояние: первый рабочий срез в разработке #

Решение от 9 августа: выпускается первый рабочий срез — примерно 50–60 операций по тому, что продукт уже умеет руками. Курсы, модули, уроки и их содержимое, файлы, люди, доступы, прогресс, сертификаты, подписки на события.

Точный перечень назовёт код, а не мы: спецификация соберётся из валидаторов, и каталог рабочих операций появится из неё — на подготовленное место, а не в спешке. До выкатки среза маршрутов нет, и проверить запросы не обо что.

Почему граница именно такая и что остаётся проектом — Состав среза и граница.

С чего начать #

Дальше — справочные страницы: Аутентификация, Ключи, Формат, Пагинация, Лимиты, Ошибки, Идемпотентность, Вебхуки, Песочница.

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

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

Машинная спецификация #

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

Черновик всего замысла лежит на /openapi.draft.json и останется там — это каталог Проекта API.

Остальной замысел #

Продажи, рассылки, сценарии, вебинары, сегменты, аналитика спроектированы, но не реализованы — их каталог, с честными пометками, в разделе Проект API. Операции будут переезжать оттуда сюда по мере реализации; адреса каталога при этом не меняются.