API

Машинна специфікація всіх маршрутів — в описі API: api.pythoncourse.me/openapi.json. Нижче — провідник для платформи школи, що подає студентські роботи через API: як прийняти відповіді на тест і що перевіряється в коментарі студента.

Тест як подача

Тест подається не файлом, а відповідями на його питання. Обидва маршрути нижче — ключ доступу школи в заголовку X-API-Key зі сферою CHECK, та сама, що й для подачі файлом. Ключ без цієї сфери отримує 403 Requires scope: check.

Тест перевіряється за правильними відповідями, які автор позначив у самому тесті (див. Для авторів), і маршрути нижче бачать лише версію, яку автор опублікував; рецензія приходить вебхуком, як і на файл.

Прочитати тест

curl https://api.pythoncourse.me/api/v1/homework/tasks/$TASK_ID/test \
     -H "X-API-Key: $CHECK_KEY"

Відповідь 200 — рівно три поля:

{
  "version": "3f9c1e…",
  "accepting_answers": true,
  "questions": [
    {
      "number": "1",
      "text": "Що таке контекстне вікно моделі?",
      "options": [
        {"label": "а", "text": "Вікно редактора, у якому агент показує зміни"},
        {"label": "б", "text": "Обсяг тексту, який модель бачить за один виклик"}
      ]
    }
  ]
}

• version — поточна версія тесту. Надсилайте її назад як test_version разом із відповідями.
• accepting_answers — чи приймаються відповіді зараз. Поки false, подача відмовляється кодом TEST_FORM_UNAVAILABLE — показуйте студентові тест, але не приймайте відповідей.
• questions — питання й варіанти опублікованої версії: номер і текст питання, мітка й текст кожного варіанта. Тексти — так, як їх записав автор; номери й мітки ставить система за порядком — українськими літерами для курсу українською, малими латинськими для решти.

Нічого з ключа тут немає: ні правильних варіантів, ні того, скільки їх у питанні, ні пояснень. Питання, де правильних відповідей кілька, автор позначає словами в тексті питання, тож показуйте біля кожного варіанта прапорець.

404 Task not found. — однакова відповідь на завдання, якого немає, видалене, завдання іншої школи й завдання, що не є опублікованим тестом: інший матеріал або тест, якого автор ще не опублікував.

Надіслати відповіді

curl -X POST https://api.pythoncourse.me/api/v1/homework/submit-test \
     -H "X-API-Key: $CHECK_KEY" -H "Content-Type: application/json" \
     -d '{
           "student_external_id": "student-42",
           "course_node_id": "…",
           "node_id": "…",
           "authored_document_id": "…",
           "answers": {"1": ["б"], "2": ["а", "в"]},
           "test_version": "3f9c1e…",
           "response_language": "en"
         }'

поле	обов'язкове	що це
student_external_id	так	ідентифікатор студента у вашій системі
course_node_id	так	курс
node_id	так	вузол курсу, до якого належить тест
authored_document_id	так	сам тест
answers	так	номер питання → мітки позначених варіантів
test_version	ні	version, яку повернуло читання тесту
webhook_url	ні	адреса вебхука для цієї подачі; без неї — типова адреса школи
response_language	ні	мова рецензії, код ISO 639-1 або 639-3
student_note	ні	коментар студента до спроби, до 2 000 знаків (див. Коментар студента)

Відповіді. Надсилайте кожну мітку саме так, як її показав маршрут структури (label), — тими самими літерами й у тому самому регістрі. Питання без відповіді не відмовляється — воно рахується неправильним. Питання чи мітка, яких у тесті немає, — відмова ANSWERS_DO_NOT_MATCH_TEST.

Версія тесту. test_version необов'язкова. Якщо її надіслано й вона не поточна — відмова TEST_VERSION_CHANGED: тест змінився, поки студент відповідав. Без неї відповіді звіряються з поточною версією.

202 — подачу прийнято:

{"submission_id": "…", "student_id": "…", "status": "received", "job_id": "…", "duplicate": false}

Ті самі відповіді, надіслані двічі, — дві спроби: кожна перевіряється й отримує власну рецензію.

Курс, вузол і завдання перевіряються так само, як у подачі файлом: 404 на те, чого у вашій школі немає, — і та сама 404 Task not found. на завдання, що не є опублікованим тестом. Далі — власні перевірки тесту, кожна зі своїм кодом (див. Відмови подачі тесту).

Файл на тестове завдання маршрутом подачі файла (POST /api/v1/homework/submit) відмовляється кодом TEST_ANSWERS_REQUIRED, а на тест, якого автор ще не опублікував, — 404 Task not found., як на відсутнє завдання.

Рецензія у вебхуку

Рецензію на тест приносить подія reviewed — та сама, що й для файла, з тими самими полями. Для тесту вони означають таке:

поле	для тесту
review.score	частка правильних відповідей, ціле число відсотків, округлене вниз
review.passed	чи досягнуто поріг заліку; якщо автор порогу не задав — true: планки, якої можна не взяти, немає
review.correctness	з балу: 100 → correct, 0 → incorrect, інакше → partially_correct
review.review_text	рецензія текстом (Markdown) — її можна показати студентові як є
structure.test	те саме по питаннях: number, correct, correct_answer (мітка й текст правильних варіантів), explanation; а також score, explanations_in_course_language, retry_offer

Якщо рецензію скласти не вдалося, приходить подія failed із причиною в reason:

path_failed

Подачу не вдалося перевірити через збій на нашому боці, і рецензії на неї не буде. Запропонуйте студентові надіслати відповіді ще раз.

test_not_ready

Для тестів, створених у системі, не надходить: подачу перевіряють за версією тесту, на яку її прийнято, а опублікована версія завжди має правильні відповіді. Раніше ця причина означала, що поки подача чекала перевірки, автор прибрав або змінив ключ відповідей. Якщо ваша платформа її вже обробляє, обробку можна лишити: скажіть студентові, що тест тимчасово не приймає відповідей, і запропонуйте спробувати пізніше.

Відмови подачі тесту

Відмова приходить до того, як щось збережено: подачі не створено, нічого не записано. У полі detail — код причини й пояснення, {"code": "…", "details": "…"}. Код — для вашого коду; слова для студента добирайте самі за кодом, details — запасний текст для коду, якого ваша платформа ще не знає.

Перевірки йдуть у такому порядку: чи тест приймає відповіді взагалі → чи та версія → чи збігаються питання й мітки → коментар студента (див. Коментар студента). Тож на подачу з кількома вадами приходить код першої.

TEST_ANSWERS_REQUIRED

422. На тест надіслано файл. Тест складається відповідями: надішліть їх маршрутом POST /api/v1/homework/submit-test.

TEST_FORM_UNAVAILABLE

409. Тести тимчасово не приймаються відповідями. Файлом тест, створений у системі, теж не складається, тож скажіть студентові, що тест тимчасово недоступний, і спробуйте пізніше — коли читання тесту знову покаже accepting_answers: true.

NOT_A_TEST_TASK

422. Для тестів, створених у системі, не видається: на завдання, що не є опублікованим тестом, маршрути тесту відповідають 404 Task not found.. Раніше цей код означав, що завдання — не тест. Якщо ваша платформа його вже обробляє, обробку можна лишити: надішліть роботу файлом або перевірте, що вказано саме тестове завдання.

TEST_VERSION_CHANGED

409. Відповіді дано на версію тесту, яка вже не поточна: автор змінив тест, поки студент відповідав. Прочитайте тест знову, покажіть студентові нову версію й надішліть відповіді на неї.

TEST_NOT_READY

409. Для тестів, створених у системі, не видається: опублікована версія тесту завжди має правильні відповіді, а неопублікованого тесту маршрути не бачать зовсім. Раніше цей код означав, що для поточної версії тесту немає ключа відповідей. Якщо ваша платформа його вже обробляє, обробку можна лишити: скажіть студентові, що тест ще не готовий, і спробуйте пізніше.

ANSWERS_DO_NOT_MATCH_TEST

422. Відповіді називають питання або варіант, яких у тесті немає; details перелічує їх. Звірте відповіді з читанням тесту — номери питань і мітки варіантів — і надішліть їх знову.

Коментар студента

До подачі файлом (POST /api/v1/homework/submit, поле форми student_note) і до відповідей на тест (POST /api/v1/homework/submit-test, поле student_note) студент може додати коментар — питання чи уточнення до роботи. Коментар перевіряється до того, як щось збережено:

• довжина — до 2 000 знаків; перенос рядка рахується за один знак, пробіли на початку й у кінці не рахуються й не зберігаються;
• текстові перевірки — ті самі, що й для текстових файлів подачі. Відмовляють лише символи, яких не буває в законному тексті: зміна напрямку тексту, тегові й керівні символи. Невидимі пробіли нульової ширини й фрази, схожі на вказівки системі перевірки, коментар не відкидають: їх позначено, і їх окремо оцінює модельна перевірка безпеки подачі.

Коментар, що не пройшов, відмовляється разом із подачею: нічого не збережено — ні подачі, ні файла, ні відповідей. Покажіть студентові причину, дайте виправити коментар і надішліть подачу знову. Подачу без коментаря ці перевірки не зачіпають. У подачі файлом коментар перевіряється останнім, після файла й завдання; у подачі тесту — після відповідей.

STUDENT_NOTE_TOO_LONG

422. Коментар довший за 2 000 знаків; details називає його довжину. Попросіть студента скоротити коментар.

STUDENT_NOTE_REJECTED

422. Коментар не пройшов текстової перевірки. details починається з категорії перевірки й двокрапки:

категорія	що в коментарі
suspicious_unicode	символи зміни напрямку тексту, тегові чи керівні символи; їх часто приносить текст, скопійований з іншої програми
charset_violation	рядок, що не є правильним Unicode, — наприклад, самотній сурогат \ud800 у JSON

Попросіть студента переписати коментар без цього.