feat: Add comprehensive API endpoint reference and usage examples documentation.
This commit is contained in:
JakkrapartXD
parent
f1ec47a674
commit
d7e37868f2
2 changed files with 1499 additions and 0 deletions
306
docs/api_endpoints.md
Normal file
306
docs/api_endpoints.md
Normal file
|
|
@ -0,0 +1,306 @@
|
|||
# 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 |
|
||||
| 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
|
||||
1193
docs/api_usage_examples.md
Normal file
1193
docs/api_usage_examples.md
Normal file
File diff suppressed because it is too large
Load diff
Loading…
Add table
Add a link
Reference in a new issue