📘 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"]
    }
  ]
}

Exercise Type Karaoke Audio Design Challenges

Before providing the API specs for the second type of the exercises page, there's some design challenges related to handling audio files in the API response we should take into consideration.

---

Design Challenge 1: Base64 Encoding of Audio

Problem: How to include audio in the API response.
Option: Encode the audio as a Base64 string in the JSON.

---

Design Challenge 2: Referencing Audio by Path/URL

Problem: How to reference audio in the API response.
Option: Store the audio externally and include the file path or URL in the JSON.

---

Design Challenge 3: Hybrid Approach

Problem: Flexibility in handling audio.
Option: Provide both a file path and Base64-encoded audio in the JSON.

---

Proposition of the Karaoke Exercise JSON Structure

This proposition uses one solution of the different design challenges mentioned above and is designed for a karaoke type exercise where audio is associated with tasks that guide the user through the exercise. The audio path points to the MP3 file used in the exercise. Each task contains a segment of the lyrics that should be highlighted in sync with the audio playback.

In this structure:

• The audio is stored as a file path to the MP3.
• The tasks are broken down by segments of the audio, and each segment corresponds to a specific time range defined by start_time and end_time.
• The highlighted_text field will now represent words rather than full sentences, providing more granular control for highlighting.

Here’s the updated JSON example:

{
    "exercise_id": 1,
    "title": "Karaoke Exercise",
    "audio": "/path/to/audio/file/karaoke_exercise.mp3",
    "tags": [],
    "frame": [
        {
            "id": 1,
            "text": "The lyrics of the audio content of the frame",
            "start_time": 0,
            "end_time": 30,
            "highlighted_text": "The first word of the first sentence"
        },
        {
            "id": 2,
            "text": "Continue with the next part of the lyrics",
            "start_time": 31,
            "end_time": 60,
            "highlighted_text": "The first word of the second frame"
        }
    ]
}