# Проект API

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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