Yared Yemane 71ba71476a edit lesson form UI adjustment

2026-04-16 05:16:30 -07:00

14 KiB

Raw Blame History

Course Management API Integration Guide

This document describes the Course Management related APIs used by the admin frontend (Yimaru-Admin) and how to integrate them safely.

It is based on:

src/api/courses.api.ts
src/api/files.api.ts
src/types/course.types.ts
src/api/http.ts

1) Base setup and auth behavior

Base URL

All requests use VITE_API_BASE_URL from environment.

Authentication

Access token is sent automatically as Authorization: Bearer <access_token>.
On 401, the frontend attempts token refresh via:
- POST /auth/refresh
- payload: { access_token, refresh_token, role, member_id }
If refresh fails, auth data is cleared and user is redirected to /login.

Transport notes

Axios automatically handles multipart/form-data boundaries for file upload.
Any network failure without response also redirects to /login (current client behavior).

2) Core domain model used by frontend

Current hierarchy used by content management:

Category
- Sub-category
  - Course
    - Level (CEFR)
      - Module
        
        Sub-module
        
        Videos
        
        Lessons (question sets with set_type = QUIZ)
        
        Practices (question sets with set_type = PRACTICE)

Important migration note:

Some APIs/types are marked as legacy (Program, old Level/Module flows).
Current frontend mostly uses unified hierarchy endpoints under /course-management/... plus /question-sets and /questions.

3) File/media APIs (used by course management)

3.1 Upload media

Endpoint

POST /files/upload

Supports

media_type: "image" | "audio" | "video"
File upload via multipart (file) or URL import via JSON (source_url).

For video uploads

Can send optional title and description.

Typical response fields used by frontend

data.object_key
data.url
data.provider (MINIO or VIMEO)
data.vimeo_id
data.embed_url

Frontend wrapper functions

uploadAudioFile(fileOrUrl)
uploadImageFile(fileOrUrl)
uploadVideoFile(fileOrUrl, { title?, description? })

3.2 Resolve object key to URL

Endpoint

GET /files/url?key=<object_key>

Use case

Resolve media object key when only key is stored.

4) Category and course APIs

4.1 Get categories (normalized in frontend)

Endpoint called

GET /course-management/hierarchy

Frontend behavior

Client transforms flat hierarchy rows into category list.
Duplicated category names are merged client-side by "richest" record.

Wrapper

getCourseCategories()

4.2 Create category or sub-category

Sub-category

POST /course-management/sub-categories
body: { category_id, name }

Wrapper

createCourseCategory({ name, parent_id? })
- if parent_id exists, creates sub-category; else category.

4.3 Delete category/sub-category

DELETE /course-management/categories/:categoryId
DELETE /course-management/sub-categories/:subCategoryId

Wrappers:

deleteCourseCategory(categoryId)
deleteCourseSubCategory(subCategoryId)

4.4 Courses by category

Endpoint called

GET /course-management/hierarchy

Frontend behavior

Filters and maps rows to courses client-side.
If duplicate category names exist, it includes rows matching requested category name.

Wrapper:

getCoursesByCategory(categoryId)

4.5 Course CRUD

POST /course-management/courses
PUT /course-management/courses/:courseId
PUT /course-management/courses/:courseId (status toggle via is_active)
DELETE /course-management/courses/:courseId
POST /course-management/courses/:courseId/thumbnail

Wrappers:

createCourse(data)
updateCourse(courseId, data)
updateCourseStatus(courseId, isActive)
deleteCourse(courseId)
updateCourseThumbnail(courseId, thumbnailUrl)

5) Course hierarchy (levels/modules/sub-modules)

5.1 Get full hierarchy for one course

Endpoint

GET /course-management/courses/:courseId/hierarchy

Wrapper

getSubModulesByCourse(courseId)

Frontend behavior

Maps hierarchy rows into sub_courses shape (compatibility naming).
This is the primary source for module/sub-module tree rendering.

5.2 Create sub-module flow (composed)

createSubModule(data) is a multi-step client workflow:

POST /course-management/levels
POST /course-management/modules
POST /course-management/sub-modules

Use this when creating a new sub-module from minimal info.

5.3 Direct level/module/sub-module creation

createModuleInLevel(levelId, title, description, displayOrder?)
- POST /course-management/modules
createSubModuleInModule(moduleId, title, description, displayOrder?)
- POST /course-management/sub-modules

5.4 Update/delete sub-module

PUT /course-management/sub-modules/:subModuleId
PUT /course-management/sub-modules/:subModuleId (status payload)
DELETE /course-management/sub-modules/:subModuleId
POST /course-management/sub-courses/:subModuleId/thumbnail (compat endpoint)

Wrappers:

updateSubModule(...)
updateSubModuleStatus(...)
deleteSubModule(...)
updateSubModuleThumbnail(...)

6) Video APIs (sub-module videos)

GET /course-management/sub-modules/:subModuleId/videos
wrapper: getVideosBySubModule(subModuleId)

6.2 Create video

Two wrapper variants, same endpoint:

POST /course-management/sub-module-videos

Minimal variant

createSubCourseVideo({ sub_module_id|sub_course_id, title, description, video_url })

Extended variant

createCourseVideo({ sub_module_id|sub_course_id, title, description, video_url, duration, resolution?, visibility?, display_order?, status? })

6.3 Update/delete video

PUT /course-management/sub-module-videos/:videoId
DELETE /course-management/sub-module-videos/:videoId

Wrappers:

updateSubCourseVideo(videoId, data)
deleteSubCourseVideo(videoId)

7) Practices and lessons

7.1 Practices by sub-module

GET /question-sets/by-owner?owner_type=SUB_MODULE&owner_id=:subModuleId
wrapper: getPracticesBySubModule(subModuleId)

7.2 Create practice (composed)

createPractice(data) does:

POST /question-sets
- set_type: "PRACTICE"
- owner_type: "SUB_MODULE"
- owner_id: sub_module_id
If step 1 succeeds, links to sub-module practice:
- POST /course-management/sub-module-practices
- includes question_set_id and intro metadata

7.3 Create lesson (composed)

createLesson(data) does:

POST /question-sets
- set_type: "QUIZ"
- owner_type: "SUB_MODULE"
Link question set as lesson:
- POST /course-management/sub-module-lessons

7.4 Practice update/delete/status

PUT /course-management/practices/:practiceId
PUT /course-management/practices/:practiceId (status)
DELETE /course-management/practices/:practiceId

Wrappers:

updatePractice(...)
updatePracticeStatus(...)
deletePractice(...)

8) Question sets and questions

8.1 Question sets

GET /question-sets with optional query params
GET /question-sets/by-owner
GET /question-sets/:id
PUT /question-sets/:id
DELETE /question-sets/:id
POST /question-sets

Wrappers:

getQuestionSets(params?)
getQuestionSetsByOwner(ownerType, ownerId)
getQuestionSetById(questionSetId)
createQuestionSet(data)
updateQuestionSet(questionSetId, partialData)
deleteQuestionSet(questionSetId)

8.2 Question list within set

GET /question-sets/:questionSetId/questions
POST /question-sets/:questionSetId/questions (add by question id)

Wrappers:

getQuestionSetQuestions(questionSetId)
addQuestionToSet(questionSetId, { question_id, display_order? })

8.3 Questions CRUD

GET /questions (filters)
GET /questions/:questionId
POST /questions
PUT /questions/:questionId
DELETE /questions/:questionId

Wrappers:

getQuestions(params)
getQuestionById(questionId)
createQuestion(data)
updateQuestion(questionId, data)
deleteQuestion(questionId)

8.4 Practice-question convenience wrappers

createPracticeQuestion(data):

Creates question via POST /questions
Adds it to practice set via POST /question-sets/:practiceId/questions

updatePracticeQuestion(questionId, data):

maps to PUT /questions/:questionId

deletePracticeQuestion(questionId):

DELETE /questions/:questionId

8.5 Practice question listing endpoint variants

getPracticeQuestions(practiceId) -> GET /question-sets/:practiceId/questions
getPracticeQuestionsByPractice(practiceId, params) -> GET /practices/:practiceId/questions

Use the second when you need pagination/filtering by question type.

9) Human language specific APIs

9.1 Human language hierarchy

getHumanLanguageHierarchy()
Calls GET /course-management/hierarchy
If backend already returns nested sub_categories, uses it directly.
If backend returns flat rows, client builds nested structure and enriches each course by:
- requesting /course-management/courses/:courseId/hierarchy
- requesting /question-sets/by-owner per sub-module
- deriving lessons from question sets where set_type = "QUIZ"

This method is heavier than basic endpoints and can issue many requests.

9.2 Human language lessons by course+level

GET /course-management/human-language/courses/:courseId/lessons?cefr_level=...
wrapper: getHumanLanguageLessonsByCourse(courseId, cefrLevel)

9.3 Create human language lesson structure

createHumanLanguageLesson(data) is composed:

POST /course-management/levels
POST /course-management/modules
POST /course-management/sub-modules

10) Learning path and assessments

GET /course-management/courses/:courseId/learning-path
- wrapper: getLearningPath(courseId)
GET /question-sets/sub-courses/:subModuleId/entry-assessment
- wrapper: getSubModuleEntryAssessment(subModuleId)

11) Unsupported or stubbed features in current frontend API layer

The following wrappers are intentionally stubbed in frontend and return resolved promises (no real backend call):

getSubModulePrerequisites
addSubModulePrerequisite
removeSubModulePrerequisite
reorderCategories
reorderCourses
reorderSubModules
reorderVideos
reorderPractices

Implication:

UI may appear to support these flows, but persistence is not implemented through backend yet.

12) Legacy endpoints still exposed (backward compatibility)

These are still present in courses.api.ts but marked deprecated in types:

Programs APIs
Old levels APIs
Old modules APIs
Practices by level/module APIs

Prefer unified hierarchy/sub-module/question-set APIs for new work.

13) Integration patterns and recommendations

13.1 Safe creation flows

For practice/lesson creation, keep composed behavior:
- create question set first
- then link to sub-module entity
Handle partial failure:
- if link step fails after question set creation, frontend should show recoverable error and optionally support manual relink.

13.2 Request normalization

getQuestionSetsResponse.data can be either:
- raw array
- object with question_sets
Normalize before rendering.

13.3 Question type mapping

UI uses "SHORT"; backend commonly expects "SHORT_ANSWER".
Existing wrappers already map "SHORT" to "SHORT_ANSWER" on create/update practice question.

13.4 Media handling

Prefer using /files/upload wrappers for all media.
For Vimeo-backed responses, frontend typically consumes embed_url (and may append hash from page URL where applicable).

13.5 Retry behavior

Some hierarchy fetches use single retry (withSingleRetry) for resiliency against transient auth/network race conditions.

14) Quick endpoint index