REST API Guide¶

В этом разделе собраны все сведения о REST API Qadamic Backend: базовый адрес, требования к аутентификации, форматы ошибок и описание доступных эндпоинтов. API целиком работает поверх mock-данных, которые можно редактировать через административную панель.

Базовая информация ¶

Базовый путь API: /api/ (например, http://127.0.0.1:8000/api/ в dev)
Формат ответов: JSON
Часовой пояс: UTC
Локализация: ответы и сообщения об ошибках возвращаются на русском

Аутентификация ¶

Большинство операций доступны без авторизации. Два эндпоинта требуют аутентифицированного пользователя:

POST /api/lessons/pass_lesson/
POST /api/questions/{question_id}/

Используется JWT-аутентификация (rest_framework_simplejwt). Для локальной разработки также доступна cookie-сессия Django.

Получение токена ¶

curl -X POST https://api.qadamic.local/api/token/ \
  -H "Content-Type: application/json" \
  -d '{"username": "user", "password": "pass"}'

Успешный ответ возвращает пару access/refresh токенов.

Использование токена ¶

curl https://api.qadamic.local/api/lessons/pass_lesson/ \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"course_id": 1, "lesson_id": 42}'

Обработка ошибок ¶

Все ответы на ошибки оформлены в формате JSON.

400 Bad Request ¶

Неверные данные запроса или ошибка проверки:

{
    "detail": "Идентификатор курса не указан"
}

401 Unauthorized ¶

Отсутствует или просрочен токен:

{
    "detail": "Authentication credentials were not provided."
}

403 Forbidden ¶

Доступ запрещён:

{
    "detail": "You do not have permission to perform this action."
}

404 Not Found ¶

Mock-эндпоинт не настроен или отключён:

{
    "detail": "Эндпоинт не найден",
    "path": "/api/courses/999/",
    "method": "GET"
}

Сводка эндпоинтов ¶

Метод	Путь	Auth	Назначение
GET	`/api/courses/`	❌	Список курсов
GET	`/api/courses/{course_id}/`	❌	Детали курса
GET	`/api/courses/{course_id}/lessons/`	❌	Уроки курса
GET	`/api/lessons/{lesson_id}/`	❌	Детали урока
POST	`/api/lessons/pass_lesson/`	✅	Фиксация прогресса по уроку
GET	`/api/questions/{question_id}/`	❌	Получение вопросов теста
POST	`/api/questions/{question_id}/`	✅	Отправка ответов на вопросы

Управление mock-данными ¶

Mock-ответы хранятся в моделях MockEndpoint и MockQuestion. Редактировать их можно в админке Django:

Зайдите на /admin под пользователем-администратором.
Найдите разделы Mock Endpoints и Mock Question Endpoints.
Для добавления укажите путь (например, /api/courses/), метод и JSON.
Активируйте чекбокс is_active — только активные записи участвуют в обработке запросов.

Описания эндпоинтов ¶

GET /api/courses/¶

Возвращает список всех доступных курсов.

Пример запроса

curl https://api.qadamic.local/api/courses/

Пример ответа (200 OK)

[
    {
        "id": 1,
        "title": "Introduction to Python",
        "description": "Learn Python basics",
        "lessons_count": 5
    },
    {
        "id": 2,
        "title": "Advanced Django",
        "description": "Deep dive into Django framework",
        "lessons_count": 8
    }
]

GET /api/courses/{course_id}/¶

Возвращает детальную информацию о курсе.

Параметры пути

course_id — строковый или числовой идентификатор курса.

Пример ответа (200 OK)

{
    "id": 1,
    "title": "Introduction to Python",
    "description": "Learn Python basics",
    "lessons_count": 5,
    "category": "Programming"
}

GET /api/courses/{course_id}/lessons/¶

Список уроков для выбранного курса.

Пример ответа (200 OK)

[
    {
        "id": 101,
        "title": "Lesson 1",
        "duration": 20
    },
    {
        "id": 102,
        "title": "Lesson 2",
        "duration": 35
    }
]

GET /api/lessons/{lesson_id}/¶

Детальная информация по конкретному уроку.

Пример ответа (200 OK)

{
    "id": 101,
    "title": "Lesson 1",
    "description": "Intro lesson",
    "materials": [
        {
            "type": "video",
            "url": "https://cdn.qadamic.local/lessons/101/video.mp4"
        }
    ]
}

POST /api/lessons/pass_lesson/¶

Фиксирует прохождение урока пользователем и возвращает актуальный прогресс по курсу. Требует аутентификации.

Тело запроса

{
    "course_id": 1,
    "lesson_id": 101
}

Пример ответа (200 OK)

{
    "course_id": 1,
    "lessons_completed": [101, 102, 103]
}

Ошибки

400 — отсутствует course_id или lesson_id.

GET /api/questions/{question_id}/¶

Возвращает данные теста: список вопросов и возможные варианты ответов.

Пример ответа (200 OK)

{
    "title": "Python basics quiz",
    "questions": [
        {
            "question_id": 1,
            "text": "Как объявить функцию?",
            "choices": [
                {"id": 1, "text": "function foo()"},
                {"id": 2, "text": "def foo():"},
                {"id": 3, "text": "lambda foo"}
            ]
        }
    ]
}

POST /api/questions/{question_id}/¶

Принимает ответы пользователя на тест. Требует аутентификации. Ответ зависит от процента правильных ответов.

Тело запроса

{
    "answers": [
        {
            "question_id": 1,
            "selected_answer_ids": [2]
        },
        {
            "question_id": 2,
            "selected_answer_ids": [1, 3]
        }
    ]
}

Успешный ответ (200 OK) — при прогрессе > 80%:

{
    "result": "passed",
    "detail": "Тест пройден",
    "next_step": "course:advanced-python"
}

Ошибочный ответ (400 Bad Request) — при недостаточном прогрессе:

{
    "progress": 55.0,
    "detail": "Не правильный ответ"
}