From d7e37868f25d491752e31e80420a7ca16f8ea11f Mon Sep 17 00:00:00 2001 From: JakkrapartXD Date: Mon, 22 Dec 2025 16:41:05 +0700 Subject: [PATCH] feat: Add comprehensive API endpoint reference and usage examples documentation. --- docs/api_endpoints.md | 306 +++++++++ docs/api_usage_examples.md | 1193 ++++++++++++++++++++++++++++++++++++ 2 files changed, 1499 insertions(+) create mode 100644 docs/api_endpoints.md create mode 100644 docs/api_usage_examples.md diff --git a/docs/api_endpoints.md b/docs/api_endpoints.md new file mode 100644 index 00000000..521573d8 --- /dev/null +++ b/docs/api_endpoints.md @@ -0,0 +1,306 @@ +# API Endpoints Reference + +## Base URL +``` +Development: http://localhost:3000/api +Production: https://api.elearning.com/api +``` + +## Authentication +``` +Authorization: Bearer +``` + +--- + +## 1. Authentication & User Management + +### Authentication +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| POST | `/auth/register` | - | Register new user | +| POST | `/auth/login` | - | Login | +| POST | `/auth/logout` | ✅ | Logout | +| POST | `/auth/refresh` | ✅ | Refresh token | +| POST | `/auth/password/reset-request` | - | Request password reset | +| POST | `/auth/password/reset` | - | Reset password | + +### User Profile +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| GET | `/users/me` | ✅ | Get current user profile | +| PUT | `/users/me` | ✅ | Update profile | +| PUT | `/users/me/password` | ✅ | Change password | + +### User Management (Admin) +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| GET | `/admin/users` | 🔒 Admin | List all users | +| GET | `/admin/users/:userId` | 🔒 Admin | Get user by ID | +| PUT | `/admin/users/:userId/role` | 🔒 Admin | Update user role | +| DELETE | `/admin/users/:userId` | 🔒 Admin | Deactivate user | + +--- + +## 2. Categories + +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| GET | `/categories` | - | List categories | +| GET | `/categories/:categoryId` | - | Get category by ID | +| POST | `/admin/categories` | 🔒 Admin | Create category | +| PUT | `/admin/categories/:categoryId` | 🔒 Admin | Update category | +| DELETE | `/admin/categories/:categoryId` | 🔒 Admin | Delete category | + +--- + +## 3. Courses + +### Public Endpoints +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| GET | `/courses` | - | List courses (with filters) | +| GET | `/courses/:courseId` | - | Get course details | + +### Student Endpoints +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| POST | `/courses/:courseId/enroll` | 👨‍🎓 Student | Enroll in course | +| GET | `/students/courses` | 👨‍🎓 Student | Get my enrolled courses | +| GET | `/students/courses/:courseId/learn` | 👨‍🎓 Student | Get course learning page | +| GET | `/students/courses/:courseId/lessons/:lessonId` | 👨‍🎓 Student | Get lesson content | +| POST | `/students/courses/:courseId/lessons/:lessonId/complete` | 👨‍🎓 Student | Mark lesson as complete | + +### Instructor Endpoints +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| POST | `/instructor/courses` | 👨‍🏫 Instructor | Create course | +| GET | `/instructor/courses` | 👨‍🏫 Instructor | Get my courses | +| GET | `/instructor/courses/:courseId` | 👨‍🏫 Instructor | Get course details | +| PUT | `/instructor/courses/:courseId` | 👨‍🏫 Instructor | Update course | +| DELETE | `/instructor/courses/:courseId` | 👨‍🏫 Instructor | Delete course | +| POST | `/instructor/courses/:courseId/submit` | 👨‍🏫 Instructor | Submit for approval | + +--- + +## 4. Chapters & Lessons + +### Chapters +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| POST | `/instructor/courses/:courseId/chapters` | 👨‍🏫 Instructor | Create chapter | +| PUT | `/instructor/courses/:courseId/chapters/:chapterId` | 👨‍🏫 Instructor | Update chapter | +| DELETE | `/instructor/courses/:courseId/chapters/:chapterId` | 👨‍🏫 Instructor | Delete chapter | +| PUT | `/instructor/courses/:courseId/chapters/reorder` | 👨‍🏫 Instructor | Reorder chapters | + +### Lessons +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| POST | `/instructor/courses/:courseId/chapters/:chapterId/lessons` | 👨‍🏫 Instructor | Create lesson | +| PUT | `/instructor/courses/:courseId/lessons/:lessonId` | 👨‍🏫 Instructor | Update lesson | +| DELETE | `/instructor/courses/:courseId/lessons/:lessonId` | 👨‍🏫 Instructor | Delete lesson | +| POST | `/instructor/courses/:courseId/lessons/:lessonId/video` | 👨‍🏫 Instructor | Upload video | +| PUT | `/instructor/courses/:courseId/lessons/reorder` | 👨‍🏫 Instructor | Reorder lessons | + +--- + +## 5. Quizzes & Assessments + +### Quiz Management (Instructor) +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| POST | `/instructor/courses/:courseId/lessons/:lessonId/quiz` | 👨‍🏫 Instructor | Create quiz | +| PUT | `/instructor/quizzes/:quizId` | 👨‍🏫 Instructor | Update quiz | +| DELETE | `/instructor/quizzes/:quizId` | 👨‍🏫 Instructor | Delete quiz | +| POST | `/instructor/quizzes/:quizId/questions` | 👨‍🏫 Instructor | Add question | +| PUT | `/instructor/quizzes/:quizId/questions/:questionId` | 👨‍🏫 Instructor | Update question | +| DELETE | `/instructor/quizzes/:quizId/questions/:questionId` | 👨‍🏫 Instructor | Delete question | + +### Taking Quizzes (Student) +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| GET | `/students/quizzes/:quizId` | 👨‍🎓 Student | Get quiz | +| POST | `/students/quizzes/:quizId/submit` | 👨‍🎓 Student | Submit quiz | +| GET | `/students/quizzes/:quizId/attempts` | 👨‍🎓 Student | Get quiz results | +| GET | `/students/quizzes/:quizId/attempts/:attemptId` | 👨‍🎓 Student | Get specific attempt | + +--- + +## 6. Announcements + +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| GET | `/courses/:courseId/announcements` | ✅ | Get course announcements | +| GET | `/courses/:courseId/announcements/:announcementId` | ✅ | Get announcement details | +| POST | `/instructor/courses/:courseId/announcements` | 👨‍🏫 Instructor | Create announcement | +| PUT | `/instructor/courses/:courseId/announcements/:announcementId` | 👨‍🏫 Instructor | Update announcement | +| DELETE | `/instructor/courses/:courseId/announcements/:announcementId` | 👨‍🏫 Instructor | Delete announcement | +| GET | `/announcements/:announcementId/attachments/:attachmentId/download` | ✅ | Download attachment | + +--- + +## 7. Reports & Analytics + +### Student Reports +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| GET | `/students/progress` | 👨‍🎓 Student | Get my overall progress | +| GET | `/students/courses/:courseId/progress` | 👨‍🎓 Student | Get course progress | +| GET | `/students/courses/:courseId/certificate` | 👨‍🎓 Student | Get certificate | +| GET | `/students/certificates` | 👨‍🎓 Student | Get all certificates | + +### Instructor Reports +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| GET | `/instructor/courses/:courseId/statistics` | 👨‍🏫 Instructor | Get course statistics | +| GET | `/instructor/courses/:courseId/students` | 👨‍🏫 Instructor | Get student list | +| GET | `/instructor/courses/:courseId/students/export` | 👨‍🏫 Instructor | Export student report | +| GET | `/instructor/dashboard` | 👨‍🏫 Instructor | Get instructor dashboard | + +### Admin Dashboard +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| GET | `/admin/statistics` | 🔒 Admin | Get system statistics | +| GET | `/admin/reports/revenue` | 🔒 Admin | Get revenue report | +| GET | `/admin/reports/users` | 🔒 Admin | Get user growth report | +| GET | `/admin/reports/courses` | 🔒 Admin | Get course statistics | + +--- + +## 8. Orders & Payments + +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| POST | `/orders` | 👨‍🎓 Student | Create order | +| GET | `/orders` | ✅ | Get my orders | +| GET | `/orders/:orderId` | ✅ | Get order details | +| POST | `/orders/:orderId/payment` | 👨‍🎓 Student | Create payment | +| GET | `/orders/:orderId/payment` | ✅ | Get payment status | +| POST | `/webhooks/payment/:provider` | - | Payment webhook | + +--- + +## 9. Instructor Earnings & Withdrawals + +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| GET | `/instructor/balance` | 👨‍🏫 Instructor | Get balance | +| GET | `/instructor/earnings` | 👨‍🏫 Instructor | Get earnings history | +| POST | `/instructor/withdrawals` | 👨‍🏫 Instructor | Request withdrawal | +| GET | `/instructor/withdrawals` | 👨‍🏫 Instructor | Get withdrawal history | +| GET | `/instructor/withdrawals/:withdrawalId` | 👨‍🏫 Instructor | Get withdrawal details | + +### Admin - Withdrawal Management +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| GET | `/admin/withdrawals` | 🔒 Admin | Get all withdrawal requests | +| POST | `/admin/withdrawals/:withdrawalId/approve` | 🔒 Admin | Approve withdrawal | +| POST | `/admin/withdrawals/:withdrawalId/reject` | 🔒 Admin | Reject withdrawal | + +--- + +## 10. Admin - Course Approval + +| Method | Endpoint | Auth | Description | +|--------|----------|------|-------------| +| GET | `/admin/courses/pending` | 🔒 Admin | Get pending courses | +| GET | `/admin/courses/:courseId` | 🔒 Admin | Get course details | +| POST | `/admin/courses/:courseId/approve` | 🔒 Admin | Approve course | +| POST | `/admin/courses/:courseId/reject` | 🔒 Admin | Reject course | + +--- + +## Query Parameters + +### Common Query Parameters +| Parameter | Type | Description | Example | +|-----------|------|-------------|---------| +| `page` | integer | Page number (default: 1) | `?page=2` | +| `limit` | integer | Items per page (default: 20) | `?limit=50` | +| `sort` | string | Sort field | `?sort=created_at` | +| `order` | string | Sort order (asc/desc) | `?order=desc` | +| `search` | string | Search query | `?search=python` | +| `lang` | string | Language (th/en) | `?lang=th` | + +### Course Filters +| Parameter | Type | Description | Example | +|-----------|------|-------------|---------| +| `category` | integer | Category ID | `?category=1` | +| `is_free` | boolean | Free courses only | `?is_free=true` | +| `price_min` | decimal | Minimum price | `?price_min=0` | +| `price_max` | decimal | Maximum price | `?price_max=1000` | +| `status` | string | Course status | `?status=approved` | +| `instructor` | integer | Instructor ID | `?instructor=5` | + +--- + +## Response Codes + +| Code | Status | Description | +|------|--------|-------------| +| 200 | OK | Success | +| 201 | Created | Resource created | +| 204 | No Content | Success (no response body) | +| 400 | Bad Request | Validation error | +| 401 | Unauthorized | Invalid/missing token | +| 403 | Forbidden | Insufficient permissions | +| 404 | Not Found | Resource not found | +| 409 | Conflict | Duplicate entry | +| 422 | Unprocessable Entity | Business logic error | +| 429 | Too Many Requests | Rate limit exceeded | +| 500 | Internal Server Error | Server error | + +--- + +## Error Response Format + +```json +{ + "error": { + "code": "ERROR_CODE", + "message": "Human readable message", + "details": [ + { + "field": "email", + "message": "Email is required" + } + ] + } +} +``` + +--- + +## Permission Legend + +- `-` = Public (no authentication required) +- ✅ = Authenticated (any logged-in user) +- 👨‍🎓 Student = Student role required +- 👨‍🏫 Instructor = Instructor role required +- 🔒 Admin = Admin role required + +--- + +## Rate Limiting + +| Endpoint Type | Limit | +|--------------|-------| +| Authentication | 5 requests/minute | +| Public | 100 requests/minute | +| Authenticated | 1000 requests/hour | + +--- + +## Total Endpoints: **85+** + +- Authentication: 6 +- User Management: 4 +- Categories: 5 +- Courses: 11 +- Chapters & Lessons: 9 +- Quizzes: 10 +- Announcements: 6 +- Reports: 11 +- Orders & Payments: 7 +- Earnings & Withdrawals: 8 +- Admin: 8 diff --git a/docs/api_usage_examples.md b/docs/api_usage_examples.md new file mode 100644 index 00000000..5f580dd9 --- /dev/null +++ b/docs/api_usage_examples.md @@ -0,0 +1,1193 @@ +# API Usage Examples + +ตัวอย่างการใช้งาน API แบบละเอียดพร้อม Request/Response + +--- + +## 📋 Table of Contents + +1. [Authentication Flow](#1-authentication-flow) +2. [Student Learning Journey](#2-student-learning-journey) +3. [Instructor Course Creation](#3-instructor-course-creation) +4. [Quiz Management](#4-quiz-management) +5. [Announcements](#5-announcements) +6. [Reports & Analytics](#6-reports--analytics) +7. [Payment Flow](#7-payment-flow) +8. [Admin Operations](#8-admin-operations) + +--- + +## 1. Authentication Flow + +### 1.1 Register New User + +**Request:** +```http +POST /api/auth/register +Content-Type: application/json + +{ + "name": "John Doe", + "email": "john@example.com", + "password": "SecurePass123!", + "role": "student" +} +``` + +**Response 201:** +```json +{ + "user": { + "id": 123, + "name": "John Doe", + "email": "john@example.com", + "role": "student", + "created_at": "2024-12-22T16:00:00Z" + }, + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEyMywicm9sZSI6InN0dWRlbnQiLCJpYXQiOjE3MDMyNTk2MDAsImV4cCI6MTcwMzM0NjAwMH0.xxx", + "expiresIn": 86400 +} +``` + +--- + +### 1.2 Login + +**Request:** +```http +POST /api/auth/login +Content-Type: application/json + +{ + "email": "john@example.com", + "password": "SecurePass123!", + "rememberMe": true +} +``` + +**Response 200:** +```json +{ + "user": { + "id": 123, + "name": "John Doe", + "email": "john@example.com", + "role": "student" + }, + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "expiresIn": 2592000 +} +``` + +**Error 401:** +```json +{ + "error": { + "code": "INVALID_CREDENTIALS", + "message": "Invalid email or password" + } +} +``` + +--- + +### 1.3 Password Reset Flow + +**Step 1: Request Reset** +```http +POST /api/auth/password/reset-request +Content-Type: application/json + +{ + "email": "john@example.com" +} +``` + +**Response 200:** +```json +{ + "message": "Password reset email sent to john@example.com" +} +``` + +**Step 2: Reset Password** +```http +POST /api/auth/password/reset +Content-Type: application/json + +{ + "token": "reset_token_from_email_abc123", + "password": "NewSecurePass456!" +} +``` + +**Response 200:** +```json +{ + "message": "Password reset successfully. Please login with your new password." +} +``` + +--- + +## 2. Student Learning Journey + +### 2.1 Browse Courses + +**Request:** +```http +GET /api/courses?page=1&limit=12&category=1&search=python&lang=th&is_free=false&sort=popular +``` + +**Response 200:** +```json +{ + "data": [ + { + "id": 1, + "title": "Python สำหรับผู้เริ่มต้น", + "description": "เรียนรู้ Python จากพื้นฐานถึงขั้นสูง", + "thumbnail": "https://cdn.example.com/courses/python-101.jpg", + "price": 990, + "is_free": false, + "instructor": { + "id": 5, + "name": "Jane Smith", + "avatar": "https://cdn.example.com/avatars/jane.jpg" + }, + "category": { + "id": 1, + "name": "การเขียนโปรแกรม" + }, + "students_count": 1250, + "rating": 4.8, + "total_lessons": 45, + "total_duration": "12:30:00", + "status": "approved" + } + ], + "pagination": { + "page": 1, + "limit": 12, + "total": 150, + "totalPages": 13 + } +} +``` + +--- + +### 2.2 Get Course Details + +**Request:** +```http +GET /api/courses/1?lang=th +``` + +**Response 200:** +```json +{ + "id": 1, + "title": "Python สำหรับผู้เริ่มต้น", + "description": "เรียนรู้ Python จากพื้นฐานถึงขั้นสูง ครอบคลุมทุกหัวข้อสำคัญ", + "thumbnail": "https://cdn.example.com/courses/python-101.jpg", + "price": 990, + "is_free": false, + "status": "approved", + "instructor": { + "id": 5, + "name": "Jane Smith", + "bio": "Software Engineer with 10+ years experience", + "avatar": "https://cdn.example.com/avatars/jane.jpg", + "total_students": 5000, + "total_courses": 8 + }, + "category": { + "id": 1, + "name": "การเขียนโปรแกรม", + "description": "หลักสูตรด้านการเขียนโปรแกรม" + }, + "chapters": [ + { + "id": 1, + "title": "บทที่ 1: เริ่มต้นกับ Python", + "lessons_count": 5, + "sort_order": 1 + }, + { + "id": 2, + "title": "บทที่ 2: ตัวแปรและชนิดข้อมูล", + "lessons_count": 8, + "sort_order": 2 + } + ], + "students_count": 1250, + "rating": 4.8, + "reviews_count": 320, + "total_lessons": 45, + "total_duration": "12:30:00", + "created_at": "2024-01-15T10:00:00Z", + "updated_at": "2024-12-20T15:30:00Z" +} +``` + +--- + +### 2.3 Enroll in Course + +**Request:** +```http +POST /api/courses/1/enroll +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +**Response 201:** +```json +{ + "enrollment_id": 456, + "course_id": 1, + "user_id": 123, + "status": "enrolled", + "progress_percentage": 0, + "enrolled_at": "2024-12-22T16:05:00Z", + "message": "Successfully enrolled in Python สำหรับผู้เริ่มต้น" +} +``` + +**Error 409 (Already Enrolled):** +```json +{ + "error": { + "code": "ALREADY_ENROLLED", + "message": "You are already enrolled in this course", + "enrollment_id": 456 + } +} +``` + +--- + +### 2.4 Get Learning Page + +**Request:** +```http +GET /api/students/courses/1/learn +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +**Response 200:** +```json +{ + "course": { + "id": 1, + "title": "Python สำหรับผู้เริ่มต้น", + "instructor": { + "id": 5, + "name": "Jane Smith" + } + }, + "enrollment": { + "id": 456, + "status": "enrolled", + "progress_percentage": 35, + "enrolled_at": "2024-12-22T16:05:00Z" + }, + "chapters": [ + { + "id": 1, + "title": "บทที่ 1: เริ่มต้นกับ Python", + "sort_order": 1, + "lessons": [ + { + "id": 1, + "title": "1.1 แนะนำ Python", + "type": "video", + "duration": "00:15:30", + "is_completed": true, + "is_locked": false, + "completed_at": "2024-12-22T16:20:00Z" + }, + { + "id": 2, + "title": "1.2 ติดตั้ง Python", + "type": "video", + "duration": "00:20:00", + "is_completed": true, + "is_locked": false, + "completed_at": "2024-12-22T16:45:00Z" + }, + { + "id": 3, + "title": "1.3 แบบทดสอบท้ายบท", + "type": "quiz", + "is_completed": false, + "is_locked": false + } + ] + }, + { + "id": 2, + "title": "บทที่ 2: ตัวแปรและชนิดข้อมูล", + "sort_order": 2, + "lessons": [ + { + "id": 4, + "title": "2.1 ตัวแปรใน Python", + "type": "video", + "duration": "00:18:00", + "is_completed": false, + "is_locked": false + } + ] + } + ] +} +``` + +--- + +### 2.5 Get Lesson Content + +**Request:** +```http +GET /api/students/courses/1/lessons/1 +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +**Response 200:** +```json +{ + "id": 1, + "title": "1.1 แนะนำ Python", + "content": { + "th": "

แนะนำ Python

Python เป็นภาษาโปรแกรมที่...

", + "en": "

Introduction to Python

Python is a programming language...

" + }, + "type": "video", + "video_url": "https://cdn.example.com/videos/lesson-1.m3u8", + "duration": "00:15:30", + "is_completed": true, + "completed_at": "2024-12-22T16:20:00Z", + "can_access": true, + "next_lesson_id": 2, + "prev_lesson_id": null, + "chapter": { + "id": 1, + "title": "บทที่ 1: เริ่มต้นกับ Python" + } +} +``` + +**Error 403 (Locked Lesson):** +```json +{ + "error": { + "code": "LESSON_LOCKED", + "message": "Please complete previous lessons first", + "required_lessons": [1, 2], + "next_available_lesson": 3 + } +} +``` + +--- + +### 2.6 Mark Lesson as Complete + +**Request:** +```http +POST /api/students/courses/1/lessons/1/complete +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +**Response 200:** +```json +{ + "lesson_id": 1, + "is_completed": true, + "completed_at": "2024-12-22T16:20:00Z", + "progress_percentage": 38, + "next_lesson": { + "id": 2, + "title": "1.2 ติดตั้ง Python", + "is_locked": false + } +} +``` + +--- + +## 3. Instructor Course Creation + +### 3.1 Create Course + +**Request:** +```http +POST /api/instructor/courses +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +Content-Type: application/json + +{ + "title": { + "th": "JavaScript สำหรับผู้เริ่มต้น", + "en": "JavaScript for Beginners" + }, + "description": { + "th": "เรียนรู้ JavaScript จากพื้นฐาน", + "en": "Learn JavaScript from scratch" + }, + "category_id": 1, + "price": 1200, + "is_free": false, + "thumbnail": "https://cdn.example.com/thumbnails/js-101.jpg" +} +``` + +**Response 201:** +```json +{ + "id": 25, + "title": { + "th": "JavaScript สำหรับผู้เริ่มต้น", + "en": "JavaScript for Beginners" + }, + "description": { + "th": "เรียนรู้ JavaScript จากพื้นฐาน", + "en": "Learn JavaScript from scratch" + }, + "category_id": 1, + "price": 1200, + "is_free": false, + "status": "draft", + "instructor_id": 5, + "created_at": "2024-12-22T16:30:00Z", + "message": "Course created successfully. Add chapters and lessons to continue." +} +``` + +--- + +### 3.2 Create Chapter + +**Request:** +```http +POST /api/instructor/courses/25/chapters +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +Content-Type: application/json + +{ + "title": { + "th": "บทที่ 1: เริ่มต้นกับ JavaScript", + "en": "Chapter 1: Getting Started with JavaScript" + }, + "sort_order": 1 +} +``` + +**Response 201:** +```json +{ + "id": 50, + "course_id": 25, + "title": { + "th": "บทที่ 1: เริ่มต้นกับ JavaScript", + "en": "Chapter 1: Getting Started with JavaScript" + }, + "sort_order": 1, + "created_at": "2024-12-22T16:32:00Z" +} +``` + +--- + +### 3.3 Create Lesson with Video + +**Request:** +```http +POST /api/instructor/courses/25/chapters/50/lessons +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +Content-Type: application/json + +{ + "title": { + "th": "1.1 แนะนำ JavaScript", + "en": "1.1 Introduction to JavaScript" + }, + "content": { + "th": "

JavaScript เป็นภาษาโปรแกรมที่ใช้ในการพัฒนาเว็บไซต์

", + "en": "

JavaScript is a programming language used for web development

" + }, + "type": "video", + "sort_order": 1 +} +``` + +**Response 201:** +```json +{ + "id": 100, + "chapter_id": 50, + "title": { + "th": "1.1 แนะนำ JavaScript", + "en": "1.1 Introduction to JavaScript" + }, + "content": { + "th": "

JavaScript เป็นภาษาโปรแกรมที่ใช้ในการพัฒนาเว็บไซต์

", + "en": "

JavaScript is a programming language used for web development

" + }, + "type": "video", + "video_url": null, + "sort_order": 1, + "created_at": "2024-12-22T16:35:00Z", + "message": "Lesson created. Upload video to complete." +} +``` + +--- + +### 3.4 Upload Video + +**Request:** +```http +POST /api/instructor/courses/25/lessons/100/video +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +Content-Type: multipart/form-data + +file: +``` + +**Response 200:** +```json +{ + "lesson_id": 100, + "video_url": "https://cdn.example.com/videos/course-25/lesson-100.m3u8", + "duration": "00:15:30", + "file_size": 52428800, + "upload_completed_at": "2024-12-22T16:40:00Z" +} +``` + +--- + +### 3.5 Submit Course for Approval + +**Request:** +```http +POST /api/instructor/courses/25/submit +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +**Response 200:** +```json +{ + "id": 25, + "status": "pending", + "submitted_at": "2024-12-22T16:45:00Z", + "message": "Course submitted for approval. You will be notified once reviewed." +} +``` + +**Error 422 (Incomplete Course):** +```json +{ + "error": { + "code": "INCOMPLETE_COURSE", + "message": "Course must have at least 1 chapter and 3 lessons", + "details": { + "chapters_count": 1, + "lessons_count": 1, + "required_lessons": 3 + } + } +} +``` + +--- + +## 4. Quiz Management + +### 4.1 Create Quiz (Instructor) + +**Request:** +```http +POST /api/instructor/courses/25/lessons/103/quiz +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +Content-Type: application/json + +{ + "title": { + "th": "แบบทดสอบท้ายบทที่ 1", + "en": "Chapter 1 Quiz" + }, + "passing_score": 70, + "time_limit": 30, + "max_attempts": 3, + "cooldown_minutes": 60, + "score_policy": "highest" +} +``` + +**Response 201:** +```json +{ + "id": 15, + "lesson_id": 103, + "title": { + "th": "แบบทดสอบท้ายบทที่ 1", + "en": "Chapter 1 Quiz" + }, + "passing_score": 70, + "time_limit": 30, + "max_attempts": 3, + "cooldown_minutes": 60, + "score_policy": "highest", + "created_at": "2024-12-22T16:50:00Z" +} +``` + +--- + +### 4.2 Add Question + +**Request:** +```http +POST /api/instructor/quizzes/15/questions +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +Content-Type: application/json + +{ + "question": { + "th": "JavaScript ย่อมาจากอะไร?", + "en": "What does JavaScript stand for?" + }, + "question_type": "multiple_choice", + "score": 10, + "sort_order": 1, + "choices": [ + { + "text": { + "th": "Java Script Language", + "en": "Java Script Language" + }, + "is_correct": false, + "sort_order": 1 + }, + { + "text": { + "th": "ไม่ได้ย่อมาจากอะไร เป็นชื่อภาษา", + "en": "It's not an acronym, it's a language name" + }, + "is_correct": true, + "sort_order": 2 + }, + { + "text": { + "th": "Just Another Scripting Language", + "en": "Just Another Scripting Language" + }, + "is_correct": false, + "sort_order": 3 + } + ] +} +``` + +**Response 201:** +```json +{ + "id": 45, + "quiz_id": 15, + "question": { + "th": "JavaScript ย่อมาจากอะไร?", + "en": "What does JavaScript stand for?" + }, + "question_type": "multiple_choice", + "score": 10, + "sort_order": 1, + "choices": [ + { + "id": 180, + "text": { + "th": "Java Script Language", + "en": "Java Script Language" + }, + "is_correct": false, + "sort_order": 1 + }, + { + "id": 181, + "text": { + "th": "ไม่ได้ย่อมาจากอะไร เป็นชื่อภาษา", + "en": "It's not an acronym, it's a language name" + }, + "is_correct": true, + "sort_order": 2 + }, + { + "id": 182, + "text": { + "th": "Just Another Scripting Language", + "en": "Just Another Scripting Language" + }, + "is_correct": false, + "sort_order": 3 + } + ], + "created_at": "2024-12-22T16:55:00Z" +} +``` + +--- + +### 4.3 Take Quiz (Student) + +**Step 1: Get Quiz** +```http +GET /api/students/quizzes/15 +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +**Response 200:** +```json +{ + "id": 15, + "title": "แบบทดสอบท้ายบทที่ 1", + "passing_score": 70, + "time_limit": 30, + "max_attempts": 3, + "cooldown_minutes": 60, + "score_policy": "highest", + "attempts_used": 1, + "can_take": true, + "next_attempt_at": null, + "best_score": 60, + "questions": [ + { + "id": 45, + "question": "JavaScript ย่อมาจากอะไร?", + "question_type": "multiple_choice", + "score": 10, + "sort_order": 1, + "choices": [ + { + "id": 180, + "text": "Java Script Language", + "sort_order": 1 + }, + { + "id": 181, + "text": "ไม่ได้ย่อมาจากอะไร เป็นชื่อภาษา", + "sort_order": 2 + }, + { + "id": 182, + "text": "Just Another Scripting Language", + "sort_order": 3 + } + ] + } + ] +} +``` + +**Step 2: Submit Quiz** +```http +POST /api/students/quizzes/15/submit +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +Content-Type: application/json + +{ + "answers": [ + { + "question_id": 45, + "choice_id": 181 + }, + { + "question_id": 46, + "choice_id": 185 + } + ] +} +``` + +**Response 200:** +```json +{ + "attempt_id": 89, + "score": 85, + "total_questions": 10, + "correct_answers": 8, + "is_passed": true, + "attempt_number": 2, + "started_at": "2024-12-22T17:00:00Z", + "completed_at": "2024-12-22T17:15:00Z", + "time_spent": "00:15:00", + "answers": [ + { + "question_id": 45, + "selected_choice_id": 181, + "is_correct": true, + "score_earned": 10 + }, + { + "question_id": 46, + "selected_choice_id": 185, + "is_correct": false, + "score_earned": 0, + "correct_choice_id": 186 + } + ] +} +``` + +--- + +## 5. Announcements + +### 5.1 Create Announcement with Attachments + +**Request:** +```http +POST /api/instructor/courses/1/announcements +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +Content-Type: multipart/form-data + +title: {"th": "ประกาศสำคัญ: เปลี่ยนแปลงตารางเรียน", "en": "Important: Schedule Change"} +content: {"th": "เนื้อหาประกาศ...", "en": "Announcement content..."} +is_pinned: true +published_at: 2024-12-25T10:00:00Z +attachments[]: +attachments[]: +``` + +**Response 201:** +```json +{ + "id": 78, + "course_id": 1, + "instructor_id": 5, + "title": { + "th": "ประกาศสำคัญ: เปลี่ยนแปลงตารางเรียน", + "en": "Important: Schedule Change" + }, + "content": { + "th": "เนื้อหาประกาศ...", + "en": "Announcement content..." + }, + "is_pinned": true, + "published_at": "2024-12-25T10:00:00Z", + "attachments": [ + { + "id": 120, + "file_name": "file1.pdf", + "file_size": 2048576, + "mime_type": "application/pdf", + "download_url": "https://api.example.com/announcements/78/attachments/120/download" + }, + { + "id": 121, + "file_name": "file2.docx", + "file_size": 1024000, + "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document", + "download_url": "https://api.example.com/announcements/78/attachments/121/download" + } + ], + "created_at": "2024-12-22T17:20:00Z" +} +``` + +--- + +### 5.2 Get Course Announcements + +**Request:** +```http +GET /api/courses/1/announcements?page=1&limit=10 +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +**Response 200:** +```json +{ + "data": [ + { + "id": 78, + "title": "ประกาศสำคัญ: เปลี่ยนแปลงตารางเรียน", + "content": "เนื้อหาประกาศ...", + "is_pinned": true, + "published_at": "2024-12-25T10:00:00Z", + "instructor": { + "id": 5, + "name": "Jane Smith", + "avatar": "https://cdn.example.com/avatars/jane.jpg" + }, + "attachments_count": 2, + "created_at": "2024-12-22T17:20:00Z" + } + ], + "pagination": { + "page": 1, + "limit": 10, + "total": 25, + "totalPages": 3 + } +} +``` + +--- + +## 6. Reports & Analytics + +### 6.1 Student Progress Report + +**Request:** +```http +GET /api/students/courses/1/progress +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +**Response 200:** +```json +{ + "course": { + "id": 1, + "title": "Python สำหรับผู้เริ่มต้น" + }, + "enrollment": { + "enrolled_at": "2024-12-22T16:05:00Z", + "status": "enrolled" + }, + "progress_percentage": 65, + "completed_lessons": 29, + "total_lessons": 45, + "completed_quizzes": 3, + "total_quizzes": 5, + "quiz_scores": [ + { + "quiz_id": 1, + "title": "แบบทดสอบบทที่ 1", + "best_score": 85, + "attempts": 2, + "is_passed": true + }, + { + "quiz_id": 2, + "title": "แบบทดสอบบทที่ 2", + "best_score": 90, + "attempts": 1, + "is_passed": true + } + ], + "time_spent": "08:45:30", + "last_activity": "2024-12-22T17:00:00Z", + "estimated_completion": "2024-12-30T00:00:00Z" +} +``` + +--- + +### 6.2 Instructor Course Statistics + +**Request:** +```http +GET /api/instructor/courses/1/statistics +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +**Response 200:** +```json +{ + "course": { + "id": 1, + "title": "Python สำหรับผู้เริ่มต้น" + }, + "total_students": 1250, + "active_students": 850, + "completed_students": 400, + "average_progress": 68, + "average_rating": 4.8, + "total_reviews": 320, + "total_revenue": 1237500, + "completion_rate": 32, + "average_completion_time": "45 days", + "quiz_statistics": { + "average_score": 78, + "pass_rate": 85 + }, + "engagement": { + "daily_active_users": 120, + "weekly_active_users": 450, + "monthly_active_users": 850 + } +} +``` + +--- + +## 7. Payment Flow + +### 7.1 Create Order + +**Request:** +```http +POST /api/orders +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +Content-Type: application/json + +{ + "course_ids": [1, 5, 8] +} +``` + +**Response 201:** +```json +{ + "order_id": 567, + "user_id": 123, + "total_amount": 3570, + "status": "pending", + "items": [ + { + "course_id": 1, + "title": "Python สำหรับผู้เริ่มต้น", + "price": 990 + }, + { + "course_id": 5, + "title": "JavaScript Advanced", + "price": 1290 + }, + { + "course_id": 8, + "title": "React Fundamentals", + "price": 1290 + } + ], + "created_at": "2024-12-22T17:30:00Z", + "expires_at": "2024-12-22T18:30:00Z" +} +``` + +--- + +### 7.2 Process Payment + +**Request:** +```http +POST /api/orders/567/payment +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +Content-Type: application/json + +{ + "provider": "stripe", + "payment_method_id": "pm_1234567890" +} +``` + +**Response 200:** +```json +{ + "payment_id": 890, + "order_id": 567, + "status": "success", + "provider": "stripe", + "transaction_id": "txn_abc123xyz", + "amount": 3570, + "paid_at": "2024-12-22T17:32:00Z", + "enrollments_created": [ + { + "course_id": 1, + "enrollment_id": 456 + }, + { + "course_id": 5, + "enrollment_id": 457 + }, + { + "course_id": 8, + "enrollment_id": 458 + } + ] +} +``` + +--- + +## 8. Admin Operations + +### 8.1 Approve Course + +**Request:** +```http +POST /api/admin/courses/25/approve +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +**Response 200:** +```json +{ + "id": 25, + "title": "JavaScript สำหรับผู้เริ่มต้น", + "status": "approved", + "approved_by": 1, + "approved_at": "2024-12-22T17:40:00Z", + "message": "Course approved successfully. Instructor has been notified." +} +``` + +--- + +### 8.2 System Statistics + +**Request:** +```http +GET /api/admin/statistics +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... +``` + +**Response 200:** +```json +{ + "users": { + "total": 10000, + "students": 9850, + "instructors": 150, + "admins": 5, + "new_this_month": 450 + }, + "courses": { + "total": 500, + "approved": 450, + "pending": 30, + "rejected": 20, + "new_this_month": 25 + }, + "enrollments": { + "total": 25000, + "active": 18000, + "completed": 7000, + "new_this_month": 1200 + }, + "revenue": { + "total": 12500000, + "this_month": 850000, + "last_month": 780000, + "growth_percentage": 8.97 + }, + "engagement": { + "daily_active_users": 2500, + "weekly_active_users": 6000, + "monthly_active_users": 9000 + } +} +``` + +--- + +## 📝 Notes + +- All timestamps are in ISO 8601 format (UTC) +- All monetary values are in THB (Thai Baht) +- File sizes are in bytes +- Durations are in HH:MM:SS format +- Multi-language fields support `th` and `en` keys