elearning/docs/api-docs/api_endpoints.md

# API Endpoints Reference

## Base URL
```
Development: http://localhost:3000/api
Production: https://api.elearning.com/api
```

## Authentication
```
Authorization: Bearer <token>
```

---

## 1. Authentication & User Management

### Authentication
| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| POST | `/auth/register` | - | Register new user (username + email) |
| POST | `/auth/login` | - | Login (username OR email) |
| 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 info |
| GET | `/users/me/profile` | ✅ | Get user profile details |
| PUT | `/users/me/profile` | ✅ | Update profile (name, phone, avatar) |
| 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 |

### Role Management (Admin)
| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| GET | `/admin/roles` | 🔒 Admin | List all roles |
| GET | `/admin/roles/:roleId` | 🔒 Admin | Get role details |

---

## 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 | `/students/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 (with lock status) |
| GET | `/students/courses/:courseId/lessons/:lessonId` | 👨‍🎓 Student | Get lesson content (checks prerequisites) |
| GET | `/students/courses/:courseId/lessons/:lessonId/access-check` | 👨‍🎓 Student | Check lesson access without loading content |
| POST | `/students/lessons/:lessonId/progress` | 👨‍🎓 Student | Save video progress |
| GET | `/students/lessons/:lessonId/progress` | 👨‍🎓 Student | Get video progress |
| 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 |
| POST | `/instructor/courses/:courseId/clone` | 👨‍🏫 Instructor | Clone course (copy all content) |

### Course Instructors
| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| GET | `/instructor/courses/:courseId/instructors` | 👨‍🏫 Instructor | List course instructors |
| POST | `/instructor/courses/:courseId/instructors` | 👨‍🏫 Instructor | Add instructor to course |
| DELETE | `/instructor/courses/:courseId/instructors/:userId` | 👨‍🏫 Instructor | Remove instructor |
| PUT | `/instructor/courses/:courseId/instructors/:userId/primary` | 👨‍🏫 Instructor | Set as primary instructor |

---

## 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 (with video & attachments) |
| PUT | `/instructor/courses/:courseId/lessons/:lessonId` | 👨‍🏫 Instructor | Update lesson |
| DELETE | `/instructor/courses/:courseId/lessons/:lessonId` | 👨‍🏫 Instructor | Delete lesson |
| PUT | `/instructor/courses/:courseId/lessons/reorder` | 👨‍🏫 Instructor | Reorder lessons |
| GET | `/instructor/courses/:courseId/lessons/:lessonId/prerequisites` | 👨‍🏫 Instructor | View lesson prerequisites |
| POST | `/instructor/courses/:courseId/lessons/:lessonId/prerequisites` | 👨‍🏫 Instructor | Update lesson prerequisites |

### Lesson Attachments
| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| POST | `/instructor/courses/:courseId/lessons/:lessonId/attachments` | 👨‍🏫 Instructor | Add more attachments |
| GET | `/instructor/courses/:courseId/lessons/:lessonId/attachments` | 👨‍🏫 Instructor | List attachments |
| PUT | `/instructor/courses/:courseId/lessons/:lessonId/attachments/:attachmentId` | 👨‍🏫 Instructor | Update attachment info |
| DELETE | `/instructor/courses/:courseId/lessons/:lessonId/attachments/:attachmentId` | 👨‍🏫 Instructor | Delete attachment |
| PUT | `/instructor/courses/:courseId/lessons/:lessonId/attachments/reorder` | 👨‍🏫 Instructor | Reorder attachments |
| GET | `/students/lessons/:lessonId/attachments/:attachmentId/download` | 👨‍🎓 Student | Download attachment |

---

## 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

### Student Endpoints
| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| GET | `/students/courses/:courseId/announcements` | 👨‍🎓 Student | Get course announcements |
| GET | `/students/courses/:courseId/announcements/:announcementId` | 👨‍🎓 Student | Get announcement details |
| GET | `/students/announcements/:announcementId/attachments/:attachmentId/download` | 👨‍🎓 Student | Download attachment |

### Instructor Endpoints
| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| GET | `/instructor/courses/:courseId/announcements` | 👨‍🏫 Instructor | List announcements |
| 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 |

---

## 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 (PDF file_path) |
| GET | `/students/certificates` | 👨‍🎓 Student | Get all my 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: **107+**

- Authentication: 6
- User Management: 6 (+2 profile, +2 roles)
- Categories: 5
- Courses: 19 (+4 instructors, +1 clone)
- Chapters & Lessons: 16
- Quizzes: 10
- Announcements: 7
- Reports: 11
- Orders & Payments: 7 (อนาคต)
- Earnings & Withdrawals: 8 (อนาคต)
- Admin: 8