# API

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

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

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

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

Почему граница именно такая и что остаётся проектом —
[Состав среза и граница](/api/scope/).

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

| Страница | Что там |
|---|---|
| [Быстрый старт](/api/quickstart/) | Ключ и первый запрос за пять минут |
| [Ошибки первого дня](/api/first-day/) | Симптом → причина → починка: всё, обо что спотыкаются в первые сутки |
| [Состав среза и граница](/api/scope/) | Что входит в первый срез, что остаётся проектом и почему |

Дальше — справочные страницы: [Аутентификация](/api/auth/), [Ключи](/api/keys/),
[Формат](/api/format/), [Пагинация](/api/pagination/), [Лимиты](/api/limits/),
[Ошибки](/api/errors/), [Идемпотентность](/api/idempotency/),
[Вебхуки](/api/webhooks/), [Песочница](/api/sandbox/).

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

- **[Формат ошибки](/api/errors/)** — тело, коды, `request_id`. Задан целиком.
- **[Формат конверта вебхука](/api/webhooks/)** — один на все события, включая
  `previous` и `related`. Это принципиальное решение: у GetCourse три несовместимые
  схемы, и единый обработчик там написать нельзя.
- **[Каталог событий](/api/events/)** — 82 имени. Имена и есть контракт; меняться
  будет состав `data.object`, а не они.

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

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

Черновик всего замысла лежит на `/openapi.draft.json` и останется там — это каталог
[Проекта API](/api-project/).

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

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