Начало работы: API

Справочник API

Начало работы с API

Базовый адрес, сессия, форматы запросов, ошибок и списков — всё необходимое перед первым вызовом.

Маршруты раздела

Метод	Маршрут	Доступ	Назначение
`GET`	`/api/health`	Без входа	Проверить доступность приложения и базы данных.

Базовый адрес

Все маршруты начинаются с /api. В локальной разработке полный адрес обычно выглядит так:

http://localhost:3000/api

На рабочем сайте используйте его основной домен.

Как выполняется вход

В интерфейсе Latorn используется сессионная cookie NextAuth. Для серверного скрипта, CLI или настольного редактора преподаватель может создать персональный API-токен и передавать его как Authorization: Bearer …. Токены работают только в явно выбранных курсах и только с выданными правами.

const response = await fetch("/api/profile", {
  credentials: "include",
});

Токен не включает CORS автоматически: браузерному приложению на другом домене нужен собственный серверный proxy. Никогда не встраивайте токен в публичный JavaScript. Подробности и готовые примеры — в разделе API-токены.

В справочнике используются три понятных уровня доступа:

Без входа — маршрут можно вызвать без сессии.
Нужна сессия — пользователь должен войти в Latorn.
Преподаватель курса — дополнительно проверяются права внутри конкретного курса.

Формат JSON-ошибки

Большинство маршрутов возвращает ошибку в едином виде:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Проверьте поля запроса",
    "details": {}
  }
}

Сначала проверяйте HTTP-статус, затем error.code. Текст message предназначен для человека и может уточняться.

Списки и постраничная выдача

Маршруты со списками обычно принимают page (иногда также pageSize) и возвращают метаданные рядом с ресурсным массивом. Имя массива зависит от маршрута: например, courses, notifications или submissions:

{
  "meta": {
    "page": 1,
    "pageSize": 40,
    "hasNext": false,
    "hasPrevious": false,
    "total": 12
  },
  "courses": []
}

Даты передаются строками ISO 8601. Денежные суммы в платёжных и отчётных ответах передаются в копейках, если возле поля явно не указано иное.

Быстрая проверка

const response = await fetch("/api/health");
const health = await response.json();

if (!response.ok) {
  throw new Error("Latorn временно недоступен");
}