docs/lal-api-design.md

📘 LAL Project API – Exercises Endpoint

This document describes the API endpoints for managing exercises within a lesson in the LAL (Learn Arabic Language) project. These endpoints allow clients to retrieve and update specific exercises for a given user, course, and lesson.

NOTE: this is a work-in-progress API specification for the LAL (Learn Arabic Language) project.

Endpoint Structure

All exercise-related actions are scoped under a specific user, course, and lesson using the following base path:

/api/v1/{username}/courses/{course_id}/lessons/{lesson_id}/exercises

---

GET an Exercise

Retrieve a specific exercise by its ID.

Request:
GET /api/v1/{username}/courses/{course_id}/lessons/{lesson_id}/exercises/{exercise_id}

Description:
Returns the specified exercise including its list of tasks and associated tags.

Response:

{
  "exercise": {
    "id": 123,
    "tags": [],
    "tasks": [
      {
        "id": 1,
        "title": "Task Title",
        "wordtemplate": ["word1", "word2"],
        "content": "Task content goes here",
        "tags": []
      }
    ]
  }
}

---

Edit an Exercise (PUT)

Update an existing exercise by ID.

Request:
PUT /api/v1/{username}/courses/{course_id}/lessons/{lesson_id}/exercises/{exercise_id}

Description:
Modifies an existing exercise and its tasks.

Request Body:

{
  "tags": ["updated-tag"],
  "tasks": [
    {
      "id": 1,
      "title": "Updated Task Title",
      "wordtemplate": ["updated1", "updated2"],
      "content": "Updated content",
      "tags": ["grammar"]
    }
  ]
}