mabdalla/courseworx
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
courseworx/docs/02-API-Contracts.md
mmabdalla 5477297914 v2.0.2 - Complete Plugin Architecture System and Multi-Currency Implementation 
Major Features Added:
- Complete Plugin Architecture System with financial plugin
- Multi-currency support with exchange rates
- Course type system (online, classroom, hybrid)
- Attendance tracking and QR code scanning
- Classroom sessions management
- Course sections and content management
- Professional video player with authentication
- Secure media serving system
- Shopping cart and checkout system
- Financial dashboard and earnings tracking
- Trainee progress tracking
- User notes and assignments system

Backend Infrastructure:
- Plugin loader and registry system
- Multi-currency database models
- Secure media middleware
- Course access middleware
- Financial plugin with payment processing
- Database migrations for new features
- API endpoints for all new functionality

Frontend Components:
- Course management interface
- Content creation and editing
- Section management with drag-and-drop
- Professional video player
- QR scanner for attendance
- Shopping cart and checkout flow
- Financial dashboard
- Plugin management interface
- Trainee details and progress views

This represents a major evolution of CourseWorx from a basic LMS to a comprehensive educational platform with plugin architecture.
2025-09-14 04:20:37 +03:00

12 KiB
Raw Blame History

CourseWorx API Contract Documentation

📋 Document Information

  • Version: 1.0.0
  • Last Updated: 2024-12-19
  • Author: AI Assistant
  • Status: Draft - Ready for Review

🎯 API Overview

CourseWorx provides a RESTful API for course management, user administration, and learning tracking. All endpoints require authentication via JWT tokens unless explicitly marked as public.

🔐 Authentication

JWT Token Format

Authorization: Bearer <jwt_token>

Token Structure

{
  "userId": "uuid",
  "iat": "issued_at_timestamp",
  "exp": "expiration_timestamp"
}

Public Endpoints

  • GET /api/auth/setup-status
  • POST /api/auth/setup
  • POST /api/auth/login
  • POST /api/auth/trainee-login

📊 Response Format Standards

Success Response

{
  "status": "success",
  "data": {},
  "message": "Operation completed successfully"
}

Error Response

{
  "error": "Error category",
  "message": "Human-readable message",
  "details": "Technical details (dev only)"
}

Pagination Response

{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "pages": 10
  }
}

🔑 Authentication API

Base Path: /api/auth

GET /api/auth/setup-status

Description: Check if system setup is required Access: Public Response:

{
  "setupRequired": true,
  "superAdminCount": 0
}

POST /api/auth/setup

Description: First-time system setup Access: Public (only when no super admin exists) Request Body:

{
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "password": "string",
  "phone": "string"
}

POST /api/auth/login

Description: User authentication Access: Public Request Body:

{
  "identifier": "email_or_phone",
  "password": "string"
}

Response:

{
  "token": "jwt_token",
  "user": {
    "id": "uuid",
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "role": "super_admin|trainer|trainee"
  }
}

POST /api/auth/trainee-login

Description: Trainee-specific authentication Access: Public Request Body:

{
  "identifier": "email_or_phone",
  "password": "string"
}

GET /api/auth/me

Description: Get current user information Access: Authenticated users Response: User object with profile information

PUT /api/auth/change-password

Description: Change user password Access: Authenticated users Request Body:

{
  "currentPassword": "string",
  "newPassword": "string"
}

👥 Users API

Base Path: /api/users

GET /api/users

Description: Get all users with pagination Access: Super Admin, Trainer Query Parameters:

  • page: Page number (default: 1)
  • limit: Items per page (default: 10)
  • role: Filter by role
  • search: Search by name or email

GET /api/users/:id

Description: Get user by ID Access: Super Admin, Trainer, Self Response: User object

POST /api/users

Description: Create new user Access: Super Admin Request Body:

{
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "password": "string",
  "role": "trainer|trainee",
  "phone": "string"
}

PUT /api/users/:id

Description: Update user Access: Super Admin, Self Request Body: Partial user object

DELETE /api/users/:id

Description: Delete user Access: Super Admin Response: Success message

POST /api/users/import

Description: Bulk import users from CSV Access: Super Admin Request: Multipart form with CSV file

📚 Courses API

Base Path: /api/courses

GET /api/courses

Description: Get all courses with filtering Access: Public (limited data), Authenticated (full data) Query Parameters:

  • page: Page number
  • limit: Items per page
  • category: Filter by category
  • level: Filter by difficulty level
  • trainer: Filter by trainer ID
  • published: Filter by publication status

GET /api/courses/:id

Description: Get course by ID Access: Public (limited data), Authenticated (full data) Response: Course object with sections and content

POST /api/courses

Description: Create new course Access: Super Admin, Trainer Request Body:

{
  "title": "string",
  "description": "string",
  "shortDescription": "string",
  "price": "decimal",
  "level": "beginner|intermediate|advanced",
  "category": "string",
  "tags": ["string"],
  "requirements": "string",
  "learningOutcomes": "string"
}

PUT /api/courses/:id

Description: Update course Access: Super Admin, Course Trainer Request Body: Partial course object

DELETE /api/courses/:id

Description: Delete course Access: Super Admin, Course Trainer Response: Success message

PUT /api/courses/:id/publish

Description: Publish/unpublish course Access: Super Admin, Course Trainer Request Body:

{
  "isPublished": true
}

POST /api/courses/:courseName/image

Description: Upload course image Access: Super Admin, Course Trainer Request: Multipart form with image file

🎓 Course Content API

Base Path: /api/course-content

GET /api/course-content/:courseId/content

Description: Get all content for a course Access: Authenticated users Query Parameters:

  • sectionId: Filter by section
  • type: Filter by content type
  • published: Filter by publication status

GET /api/course-content/:courseId/content/:contentId

Description: Get specific content item Access: Authenticated users Response: Content object with metadata

POST /api/course-content/:courseId/content

Description: Create new content Access: Super Admin, Course Trainer Request Body:

{
  "title": "string",
  "description": "string",
  "type": "document|image|video|article|quiz|certificate",
  "sectionId": "uuid",
  "order": "integer",
  "points": "integer",
  "isRequired": "boolean",
  "isPublished": "boolean"
}

PUT /api/course-content/:courseId/content/:contentId

Description: Update content Access: Super Admin, Course Trainer Request Body: Partial content object

DELETE /api/course-content/:courseId/content/:contentId

Description: Delete content Access: Super Admin, Course Trainer

POST /api/course-content/:courseId/content/:contentType/upload

Description: Upload file for content Access: Super Admin, Course Trainer Request: Multipart form with file

📚 Course Sections API

Base Path: /api/course-sections

GET /api/course-sections/:courseId

Description: Get all sections for a course Access: Authenticated users Response: Array of section objects

POST /api/course-sections/:courseId

Description: Create new section Access: Super Admin, Course Trainer Request Body:

{
  "title": "string",
  "description": "string",
  "order": "integer"
}

PUT /api/course-sections/:sectionId

Description: Update section Access: Super Admin, Course Trainer Request Body: Partial section object

DELETE /api/course-sections/:sectionId

Description: Delete section Access: Super Admin, Course Trainer

🎓 Enrollments API

Base Path: /api/enrollments

GET /api/enrollments

Description: Get all enrollments (admin view) Access: Super Admin Query Parameters:

  • page: Page number
  • limit: Items per page
  • status: Filter by enrollment status
  • courseId: Filter by course

GET /api/enrollments/my

Description: Get user's enrollments Access: Authenticated users Query Parameters:

  • status: Filter by enrollment status

POST /api/enrollments

Description: Create enrollment Access: Super Admin, Trainer Request Body:

{
  "userId": "uuid",
  "courseId": "uuid",
  "status": "enrolled|completed|dropped"
}

PUT /api/enrollments/:id/status

Description: Update enrollment status Access: Super Admin, Trainer Request Body:

{
  "status": "enrolled|completed|dropped",
  "notes": "string"
}

📊 Lesson Completion API

Base Path: /api/lesson-completion

GET /api/lesson-completion/:courseId/progress

Description: Get user's progress for a course Access: Authenticated users Response:

{
  "courseId": "uuid",
  "totalContent": "integer",
  "completedContent": "integer",
  "progress": "percentage",
  "lastCompleted": "timestamp"
}

POST /api/lesson-completion/:courseId/:contentId

Description: Mark content as completed Access: Authenticated users Request Body:

{
  "completed": true,
  "timeSpent": "integer (seconds)",
  "score": "integer (if applicable)"
}

📈 Course Statistics API

Base Path: /api/course-stats

GET /api/course-stats/:courseId

Description: Get course statistics Access: Super Admin, Course Trainer Response:

{
  "courseId": "uuid",
  "totalEnrollments": "integer",
  "activeEnrollments": "integer",
  "completionRate": "percentage",
  "averageScore": "decimal",
  "totalRevenue": "decimal"
}

📝 User Notes API

Base Path: /api/user-notes

GET /api/user-notes/:courseId

Description: Get user notes for a course Access: Authenticated users Query Parameters:

  • userId: User ID (for trainers viewing student notes)

POST /api/user-notes/:courseId

Description: Create new note Access: Authenticated users Request Body:

{
  "content": "string",
  "contentId": "uuid (optional)",
  "isPrivate": "boolean"
}

🚨 Error Codes

HTTP Status Codes

  • 200: Success
  • 201: Created
  • 400: Bad Request (validation errors)
  • 401: Unauthorized (authentication required)
  • 403: Forbidden (insufficient permissions)
  • 404: Not Found
  • 409: Conflict (duplicate data)
  • 422: Unprocessable Entity
  • 500: Internal Server Error

Common Error Messages

{
  "error": "Validation Error",
  "message": "Invalid input data",
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

📱 Mobile API Considerations

Endpoint: /api/mobile-test

Description: Mobile connectivity test Access: Public Response: Connection status and device information

Mobile-Specific Headers

  • User-Agent: Device identification
  • Accept: Content type preferences
  • Authorization: JWT token

🔄 API Versioning

Current Version: v1

  • Base Path: /api
  • Version Header: Not currently implemented
  • Deprecation Policy: Not currently implemented

Future Versioning Strategy

  • URL Versioning: /api/v2/
  • Header Versioning: Accept: application/vnd.courseworx.v2+json
  • Backward Compatibility: Maintain v1 for 12 months after v2 release

📊 API Performance

Response Time Targets

  • Simple Queries: < 100ms
  • Complex Queries: < 500ms
  • File Uploads: < 5s (depending on file size)
  • Bulk Operations: < 10s

Rate Limiting

  • Current: Not implemented
  • Planned: 100 requests per minute per user
  • File Uploads: 10 uploads per minute per user

🔒 Security Considerations

Input Validation

  • SQL Injection: Prevented by Sequelize ORM
  • XSS: Input sanitization required
  • File Upload: Type and size validation
  • JWT Security: Secure token storage and transmission

Data Privacy

  • PII Protection: Email and phone number encryption
  • Role-Based Access: Strict permission controls
  • Audit Logging: Not currently implemented

Next Steps:

  1. Review and validate API contracts
  2. Implement comprehensive testing
  3. Add rate limiting and security headers
  4. Create API documentation for developers