📘 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.

2.4 KiB Raw Blame History Unescape Escape