API Contract

REST API документация проекта App Factory.

Интерактивная документация

URL	Описание
/api/docs/	Swagger UI — интерактивная документация, можно тестировать запросы
/api/redoc/	ReDoc — альтернативный формат, удобен для чтения
/api/schema/	OpenAPI schema — YAML, для импорта в Postman/Insomnia
/api/schema/?format=json	OpenAPI schema — JSON формат

URL для доступа

Production: https://app-factory.online/api/docs/ Staging: https://dev.app-factory.online/api/docs/ Local: http://localhost:8000/api/docs/

API-документация генерируется автоматически из кода через drf-spectacular.

Авторитетный источник

Ручная OpenAPI 3.0.3 спецификация: api-contract.yaml

Этот файл является единственным источником правды для API-контракта. Если автогенерируемая схема расходится с ручным контрактом — это баг в коде, не в контракте.

Текущие эндпоинты

Auth

Метод	URL	Описание	Auth
POST	/api/v1/auth/anonymous	Анонимная авторизация по device_install_id	Нет
POST	/api/v1/auth/refresh	Обновление JWT-токенов	Нет

Bootstrap

Метод	URL	Описание	Auth
GET	/api/v1/bootstrap	Полная инициализация приложения	JWT

Content

Метод	URL	Описание	Auth
GET	/api/v1/content/days/{day_index}	Контент дня (с проверкой доступа)	JWT
GET	/api/v1/content/items/{content_item_id}	Контент по UUID (без проверки доступа)	JWT
GET	/api/v1/content/manifest	Манифест для offline-синхронизации	JWT
POST	/api/v1/content/items/{content_item_id}/transition	Переход состояния контента (state machine)	Admin

Content Lifecycle State Machine:

Валидные переходы: draft→published, draft→scheduled, scheduled→draft, scheduled→published, published→archived, archived→draft.

Request body:

{"state": "published"}

Для scheduled:

{"state": "scheduled", "scheduled_publish_at": "2026-03-01T10:00:00Z"}

Response (200):

{"state": "published"}

Валидация при публикации: ≥1 translation, непустой content_hash. Неверный переход → 400.

Progress

Метод	URL	Описание	Auth
GET	/api/v1/progress?course_id=UUID&client_timezone=Asia/Tokyo	Текущий прогресс пользователя (timezone-aware offset)	JWT
POST	/api/v1/progress/complete_day	Завершить день (идемпотентно, timezone-aware streak)	JWT

Timezone support: Оба эндпоинта принимают client_timezone (IANA name, e.g. Asia/Tokyo, America/New_York). Streak рассчитывается по локальному дню клиента. time_offset_sec в ответе вычисляется по таймзону. При невалидном или отсутствующем таймзоне — fallback на UTC.

Quiz

Метод	URL	Описание	Auth
GET	/api/v1/quiz/session/next?course_id=UUID	Следующая quiz-сессия (отбор вопросов с cooldown)	JWT
POST	/api/v1/quiz/session/{session_id}/answer	Ответ на вопрос (идемпотентно)	JWT
POST	/api/v1/quiz/session/{session_id}/complete	Завершение сессии (идемпотентно)	JWT

Quiz Session содержит: session_id, course_id, mode (true_false_swipe), max_questions, questions[], scoring (correct/incorrect/streak_bonus), cooldowns.

Answer Response: is_correct, explanation, score_delta, session_progress (answered/remaining/score_total).

Complete Response: result (answered, correct, accuracy, recommended_review_tags[]).

Формат ошибок (ErrorEnvelope)

Все ошибки возвращаются в едином формате:

{
  "error": {
    "code": "validation_error",
    "message": "Human-readable description",
    "details": {"field": ["Error message"]},
    "request_id": "uuid-correlation-id"
  }
}

Коды ошибок: validation_error, authentication_error, permission_denied, not_found, method_not_allowed, throttled.