# Состав среза и граница

Раздел API разделён надвое: **«API»** — первый рабочий срез, **[Проект
API](/api-project/)** — остальной замысел. Эта страница объясняет, где проходит
граница, почему именно там и как не перепутать одно с другим.

## Правило границы — одно

> **API первого среза покрывает ровно то, что продукт уже умеет руками.**

Принцип API — паритет с интерфейсом: обе стороны вызывают одни и те же сервисы.
У этого принципа есть зеркальное следствие, и граница выводится из него:
**операция без работающей механики под ней — это контракт без реализации.**
Его нельзя проверить, по нему нельзя написать интеграцию, и единственное, что
он умеет, — разойтись с будущим кодом.

Поэтому продажи, рассылки и сценарии не получают API раньше, чем появятся
в продукте: их API был бы выдумкой с путями.

## Что входит в срез

Примерно 50–60 операций по областям, которые работают в продукте сегодня:

| Область | Что это в продукте |
|---|---|
| Курсы, модули, уроки | Структура обучения — [Курсы и уроки](/guide/courses/) |
| Содержимое урока | Дерево блоков: чтение и замена целиком |
| Файлы | Библиотека школы, загрузка, метаданные |
| Люди | Заведение, профиль, теги, произвольные поля |
| Доступы | Выдача, продление, заморозка, отзыв — [Доступы](/guide/access/) |
| Открытость урока | «Открыт ли и почему» — тем же движком, что видит ученик |
| Прогресс | Прохождение по урокам |
| Сертификаты | Выдача и проверка |
| Подписки на события | Вебхуки: подписка, журнал доставок, повтор |

**Точный перечень операций назовёт код.** Спецификация первого среза соберётся
из валидаторов, и каталог рабочих операций появится из неё — с телами запросов
и составом полей, которых у черновика нет. Числа «50–60» — план, а не обещание
с точностью до штуки.

## Что остаётся проектом

| Область | Почему |
|---|---|
| Продажи: продукты, тарифы, заказы, платежи, возвраты, чеки | [Этого нет в продукте](/guide/sales/) |
| Рассылки и шаблоны сообщений | [Нет](/guide/messaging/) |
| Сценарии | [Нет](/guide/scenarios/) |
| Вебинары | Нет |
| Сегменты, массовые действия | Нет |
| Аналитика | Нет |
| Импорт и экспорт | Нет |

Их каталог со всеми пометками — [Проект API](/api-project/).

## Как не перепутать

Три различия, все три видны без чтения мелкого шрифта:

| | «API» | «Проект API» |
|---|---|---|
| Раздел на сайте | [API](/api/) | [Проект API](/api-project/) |
| Машинная спецификация | `/openapi.json` — появится со срезом, из валидаторов | `/openapi.draft.json` — уже есть, из проектного документа |
| Чему верить | Контракт: тела, поля, коды | Замысел: пути и назначение; у 60 операций адрес предположительный |

Признаки в самом черновике: `x-lms-provisional` у документа, `x-lms-shorthand`
у выведенных адресов, `x-lms-unspecified` у операций без описанных тел. Агенту
достаточно проверить первый.

## Что произойдёт при выкатке среза

1. Появятся маршруты — и `/openapi.json` из валидаторов.
2. Каталог рабочих операций соберётся в разделе «API»; эти операции исчезнут
   из черновика.
3. С этой страницы и с раздела снимется пометка «срез в разработке».
4. Адреса существующих страниц не изменятся — включая каталог замысла
   под `/api/reference/`.

До тех пор честное состояние такое: справочные страницы раздела «API» описывают
формат, который решён и не изменится, а проверить запросы пока не обо что.