chamomind/elearning
7
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages 3 Wiki Activity Actions
elearning/docs/api-docs/api_endpoints.md

342 lines
14 KiB
Markdown
Raw Blame History

# 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
Reference in a new issue View git blame Copy permalink