Работа с API

Взаимодействие идёт по HTTP в формате REST и по WebSocket. Всё API стенда - на одном адресе https://korifei.wonk.study, разделы различаются префиксом пути. У каждого метода указан полный адрес: базовый адрес раздела и путь, например POST {API_URL}/v1/auth/login.

Базовый адрес	Разделы	Стенд
API_URL	Авторизация, Пользователи, ИИ-генерации	https://korifei.wonk.study/api
AI_URL	ИИ-чат, бланк вопросов smart questions	https://korifei.wonk.study/api/ai
DODA_URL	Дода	https://korifei.wonk.study/api/doda
COMPILER_URL	Компилятор	https://korifei.wonk.study/api/compiler

Адреса других окружений выдаёт администратор Wonk; для WebSocket схема ws:// или wss://.

Администратору Wonk школа сообщает:

• origin своих веб-клиентов, например https://app.korifei.kz: без этого браузер не пустит запросы (CORS);
• адрес своей страницы игры для учеников: из него строится ссылка join_url рядом с PIN.

Авторизация запросов

Токен выдают методы раздела «Авторизация», один токен подходит для всех методов. Токен передаётся в заголовке запроса:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

В WebSocket токен передаётся параметром адреса token: браузер не ставит заголовки на WebSocket. В остальных запросах токен в адрес не кладите: адреса попадают в логи.

Токен - JWT с подписью HS256, живёт 24 часа, обновления нет: по истечении получите новый. Отключённую учётную запись методы API_URL не пускают сразу, а методы остальных адресов принимают её токен до exp.

Claim	Тип	Описание
sub	uuid	id пользователя
profile_id	uuid	Тот же id; по нему Дода определяет хозяина тестов
role	string	teacher или school_admin
typ	string	Всегда access
first_name, last_name	string	Имя пользователя
iat, exp	integer	Время выпуска и окончания, unix-время

Роль	role	Доступ
Учитель	teacher	ИИ-генерации, ИИ-чат, Дода, компилятор
Директор	school_admin	То же и управление пользователями

Обозначения

• Поля со звёздочкой (*) обязательны.
• Типы: string, integer, number, boolean, object, array; uuid - строка с UUID; datetime - строка ISO 8601 в UTC.
• Вложенные поля записаны через точку, элементы массива - через []: options[].label.
• Кодировка UTF-8, тело запроса и ответа - JSON, если не указано иное.
• Язык контента - русский: генерации идут на русском, тексты в Доде - с ключом ru.
• Лимиты и сроки указаны по умолчанию: администратор Wonk может их изменить.

Ответ с ошибкой

Ошибка приходит с HTTP-кодом и телом:

Параметр	Тип	Описание
detail*	string	Текст ошибки; у ошибки валидации 422 - массив, кроме Доды
detail[].loc	array	Путь к полю: ["body", "email"]
detail[].msg	string	Описание ошибки поля
detail[].type	string	Тип ошибки поля
code	string	Только Дода: машинный код ошибки (раздел «Статусы и коды»)

{"detail": "Incorrect email or password."}

{"detail": "...", "code": "NICKNAME_TAKEN"}

Тексты ошибок технические, на английском: пользователю показывайте свой текст по коду ответа и code.

Код	Значение
400	Неверный файл или запрос
401	Нет токена, он недействителен или учётная запись отключена
403	Роль не позволяет действие
404	Объекта нет или он чужой
409	Конфликт состояния
413	Файл больше лимита
422	Ошибка валидации полей
429	Компилятор занят: повторите через Retry-After секунд
502	Недоступна зависимость: хранилище файлов или Дода
503	ИИ временно недоступен или функция выключена

При 502 и 503 повторяйте запрос с паузами 1, 2, 4, 8 секунд и дальше по 30 секунд.

Пагинация

Списки пользователей, генераций, тестов Доды, тредов и сообщений ИИ-чата принимают page (с 1) и page_size (до 100, по умолчанию 20) и отвечают объектом:

Параметр	Тип	Описание
items*	array	Элементы страницы
total*	integer	Всего элементов
page*	integer	Номер страницы
page_size*	integer	Размер страницы