================ REST API Guide ================ .. contents:: Содержание :depth: 2 :local: :class: this-will-duplicate-information-and-it-is-still-useful-here В этом разделе собраны все сведения о 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. Получение токена ---------------- .. code-block:: bash curl -X POST https://api.qadamic.local/api/token/ \ -H "Content-Type: application/json" \ -d '{"username": "user", "password": "pass"}' Успешный ответ возвращает пару ``access``/``refresh`` токенов. Использование токена -------------------- .. code-block:: bash curl https://api.qadamic.local/api/lessons/pass_lesson/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"course_id": 1, "lesson_id": 42}' Обработка ошибок ================ Все ответы на ошибки оформлены в формате JSON. 400 Bad Request --------------- Неверные данные запроса или ошибка проверки: .. code-block:: json { "detail": "Идентификатор курса не указан" } 401 Unauthorized ---------------- Отсутствует или просрочен токен: .. code-block:: json { "detail": "Authentication credentials were not provided." } 403 Forbidden ------------- Доступ запрещён: .. code-block:: json { "detail": "You do not have permission to perform this action." } 404 Not Found ------------- Mock-эндпоинт не настроен или отключён: .. code-block:: json { "detail": "Эндпоинт не найден", "path": "/api/courses/999/", "method": "GET" } Сводка эндпоинтов ================= .. list-table:: :header-rows: 1 :widths: 15 45 15 25 * - Метод - Путь - 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: 1. Зайдите на ``/admin`` под пользователем-администратором. 2. Найдите разделы **Mock Endpoints** и **Mock Question Endpoints**. 3. Для добавления укажите путь (например, ``/api/courses/``), метод и JSON. 4. Активируйте чекбокс ``is_active`` — только активные записи участвуют в обработке запросов. Описания эндпоинтов =================== GET /api/courses/ ----------------- Возвращает список всех доступных курсов. **Пример запроса** .. code-block:: bash curl https://api.qadamic.local/api/courses/ **Пример ответа (200 OK)** .. code-block:: json [ { "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)** .. code-block:: json { "id": 1, "title": "Introduction to Python", "description": "Learn Python basics", "lessons_count": 5, "category": "Programming" } GET /api/courses/{course_id}/lessons/ ------------------------------------- Список уроков для выбранного курса. **Пример ответа (200 OK)** .. code-block:: json [ { "id": 101, "title": "Lesson 1", "duration": 20 }, { "id": 102, "title": "Lesson 2", "duration": 35 } ] GET /api/lessons/{lesson_id}/ ----------------------------- Детальная информация по конкретному уроку. **Пример ответа (200 OK)** .. code-block:: json { "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/ ------------------------------ Фиксирует прохождение урока пользователем и возвращает актуальный прогресс по курсу. Требует аутентификации. **Тело запроса** .. code-block:: json { "course_id": 1, "lesson_id": 101 } **Пример ответа (200 OK)** .. code-block:: json { "course_id": 1, "lessons_completed": [101, 102, 103] } **Ошибки** * ``400`` — отсутствует ``course_id`` или ``lesson_id``. GET /api/questions/{question_id}/ --------------------------------- Возвращает данные теста: список вопросов и возможные варианты ответов. **Пример ответа (200 OK)** .. code-block:: json { "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}/ ---------------------------------- Принимает ответы пользователя на тест. Требует аутентификации. Ответ зависит от процента правильных ответов. **Тело запроса** .. code-block:: json { "answers": [ { "question_id": 1, "selected_answer_ids": [2] }, { "question_id": 2, "selected_answer_ids": [1, 3] } ] } **Успешный ответ (200 OK)** — при прогрессе > 80%: .. code-block:: json { "result": "passed", "detail": "Тест пройден", "next_step": "course:advanced-python" } **Ошибочный ответ (400 Bad Request)** — при недостаточном прогрессе: .. code-block:: json { "progress": 55.0, "detail": "Не правильный ответ" }