Состав среза и граница
Раздел API разделён надвое: «API» — первый рабочий срез, Проект API — остальной замысел. Эта страница объясняет, где проходит граница, почему именно там и как не перепутать одно с другим.
Правило границы — одно #
API первого среза покрывает ровно то, что продукт уже умеет руками.
Принцип API — паритет с интерфейсом: обе стороны вызывают одни и те же сервисы. У этого принципа есть зеркальное следствие, и граница выводится из него: операция без работающей механики под ней — это контракт без реализации. Его нельзя проверить, по нему нельзя написать интеграцию, и единственное, что он умеет, — разойтись с будущим кодом.
Поэтому продажи, рассылки и сценарии не получают API раньше, чем появятся в продукте: их API был бы выдумкой с путями.
Что входит в срез #
Примерно 50–60 операций по областям, которые работают в продукте сегодня:
| Область | Что это в продукте |
|---|---|
| Курсы, модули, уроки | Структура обучения — Курсы и уроки |
| Содержимое урока | Дерево блоков: чтение и замена целиком |
| Файлы | Библиотека школы, загрузка, метаданные |
| Люди | Заведение, профиль, теги, произвольные поля |
| Доступы | Выдача, продление, заморозка, отзыв — Доступы |
| Открытость урока | «Открыт ли и почему» — тем же движком, что видит ученик |
| Прогресс | Прохождение по урокам |
| Сертификаты | Выдача и проверка |
| Подписки на события | Вебхуки: подписка, журнал доставок, повтор |
Точный перечень операций назовёт код. Спецификация первого среза соберётся из валидаторов, и каталог рабочих операций появится из неё — с телами запросов и составом полей, которых у черновика нет. Числа «50–60» — план, а не обещание с точностью до штуки.
Что остаётся проектом #
| Область | Почему |
|---|---|
| Продажи: продукты, тарифы, заказы, платежи, возвраты, чеки | Этого нет в продукте |
| Рассылки и шаблоны сообщений | Нет |
| Сценарии | Нет |
| Вебинары | Нет |
| Сегменты, массовые действия | Нет |
| Аналитика | Нет |
| Импорт и экспорт | Нет |
Их каталог со всеми пометками — Проект API.
Как не перепутать #
Три различия, все три видны без чтения мелкого шрифта:
| «API» | «Проект API» | |
|---|---|---|
| Раздел на сайте | API | Проект API |
| Машинная спецификация | /openapi.json — появится со срезом, из валидаторов |
/openapi.draft.json — уже есть, из проектного документа |
| Чему верить | Контракт: тела, поля, коды | Замысел: пути и назначение; у 60 операций адрес предположительный |
Признаки в самом черновике: x-lms-provisional у документа, x-lms-shorthand
у выведенных адресов, x-lms-unspecified у операций без описанных тел. Агенту
достаточно проверить первый.
Что произойдёт при выкатке среза #
- Появятся маршруты — и
/openapi.jsonиз валидаторов. - Каталог рабочих операций соберётся в разделе «API»; эти операции исчезнут из черновика.
- С этой страницы и с раздела снимется пометка «срез в разработке».
- Адреса существующих страниц не изменятся — включая каталог замысла
под
/api/reference/.
До тех пор честное состояние такое: справочные страницы раздела «API» описывают формат, который решён и не изменится, а проверить запросы пока не обо что.