138 lines
3.8 KiB
Markdown
138 lines
3.8 KiB
Markdown
|
||
# 📘 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:**
|
||
|
||
```json
|
||
{
|
||
"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:**
|
||
|
||
```json
|
||
{
|
||
"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:
|
||
|
||
```json
|
||
{
|
||
"exercise_id": 1,
|
||
"title": "Karaoke Exercise",
|
||
"audio": "/path/to/audio/file/karaoke_exercise.mp3",
|
||
"tasks": [
|
||
{
|
||
"id": 1,
|
||
"text": "The lyrics of the audio content subtask",
|
||
"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 part of the audio"
|
||
}
|
||
]
|
||
}
|
||
``` |