Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
667 lines (549 loc) · 9.87 KB

API_DOCUMENTATION.md

File metadata and controls

667 lines (549 loc) · 9.87 KB
Raw

E-Learn API Documentation

Base URL

http://localhost:5000/api

Authentication

All protected endpoints require a Bearer token in the Authorization header:

Authorization: Bearer {token}

Authentication Endpoints

Register User

POST /auth/register

Create a new user account.

Request Body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "password123",
  "role": "student"
}

Response (201):

{
  "success": true,
  "message": "User registered successfully",
  "token": "eyJhbGc...",
  "user": {
    "id": "user_id",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "student"
  }
}

Login User

POST /auth/login

Authenticate and get access token.

Request Body:

{
  "email": "john@example.com",
  "password": "password123"
}

Response (200):

{
  "success": true,
  "message": "Login successful",
  "token": "eyJhbGc...",
  "user": {
    "id": "user_id",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "student",
    "points": 250,
    "level": 3,
    "badges": ["badge1", "badge2"]
  }
}

User Endpoints

Get User Profile

GET /users/profile

Headers: Authorization required

Response (200):

{
  "success": true,
  "user": {
    "id": "user_id",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "student",
    "points": 250,
    "level": 3,
    "badges": [
      {
        "id": "badge_id",
        "name": "Quick Learner",
        "description": "Complete 5 quizzes"
      }
    ],
    "enrolledCourses": ["course1", "course2"]
  }
}

Update User Profile

PUT /users/profile

Headers: Authorization required

Request Body:

{
  "name": "John Doe Updated",
  "bio": "Learning enthusiast",
  "profileImage": "https://example.com/image.jpg"
}

Response (200):

{
  "success": true,
  "message": "Profile updated",
  "user": { ... }
}

Enroll in Course

POST /users/enroll

Headers: Authorization required

Request Body:

{
  "courseId": "course_id"
}

Response (200):

{
  "success": true,
  "message": "Enrolled successfully",
  "course": { ... }
}

Get Enrolled Courses

GET /users/courses

Headers: Authorization required

Response (200):

{
  "success": true,
  "courses": [
    {
      "id": "course_id",
      "title": "JavaScript Basics",
      "description": "Learn JavaScript fundamentals",
      "level": "beginner",
      "lessons": 10,
      "studentCount": 150
    }
  ]
}

Course Endpoints

Get All Courses

GET /courses

Response (200):

{
  "success": true,
  "courses": [
    {
      "id": "course_id",
      "title": "JavaScript Basics",
      "description": "Learn JavaScript fundamentals",
      "category": "Programming",
      "level": "beginner",
      "instructor": {
        "name": "Jane Smith",
        "email": "jane@example.com"
      },
      "lessons": 10,
      "studentCount": 150,
      "rating": 4.5
    }
  ]
}

Get Course Details

GET /courses/{courseId}

Response (200):

{
  "success": true,
  "course": {
    "id": "course_id",
    "title": "JavaScript Basics",
    "description": "Learn JavaScript fundamentals",
    "lessons": [
      {
        "id": "lesson_id",
        "title": "Introduction to JavaScript",
        "description": "Get started with JS",
        "contentType": "video",
        "videoUrl": "https://example.com/video.mp4",
        "duration": 30,
        "quiz": {
          "id": "quiz_id",
          "title": "JS Basics Quiz",
          "questions": 10
        }
      }
    ]
  }
}

Get Course Progress

GET /courses/{courseId}/progress

Headers: Authorization required

Response (200):

{
  "success": true,
  "progress": {
    "id": "progress_id",
    "completedLessons": ["lesson1", "lesson2"],
    "completionPercentage": 40,
    "enrolledAt": "2024-01-15T10:00:00Z",
    "lastAccessedAt": "2024-01-17T14:30:00Z"
  }
}

Mark Lesson Complete

POST /courses/mark-complete

Headers: Authorization required

Request Body:

{
  "courseId": "course_id",
  "lessonId": "lesson_id"
}

Response (200):

{
  "success": true,
  "message": "Lesson marked complete",
  "progress": { ... }
}

Gamification Endpoints

Submit Quiz

POST /gamification/submit-quiz

Headers: Authorization required

Request Body:

{
  "quizId": "quiz_id",
  "lessonId": "lesson_id",
  "courseId": "course_id",
  "answers": [
    {
      "questionIndex": 0,
      "selectedAnswer": "option_a"
    },
    {
      "questionIndex": 1,
      "selectedAnswer": "option_b"
    }
  ]
}

Response (200):

{
  "success": true,
  "message": "Quiz passed!",
  "attempt": {
    "id": "attempt_id",
    "score": 8,
    "percentage": 80,
    "passed": true,
    "pointsEarned": 80,
    "completedAt": "2024-01-17T15:00:00Z"
  },
  "userPoints": 330
}

Get Quiz Attempts

GET /gamification/attempts/{quizId}

Headers: Authorization required

Response (200):

{
  "success": true,
  "attempts": [
    {
      "id": "attempt_id",
      "score": 8,
      "percentage": 80,
      "passed": true,
      "pointsEarned": 80,
      "attemptNumber": 1,
      "completedAt": "2024-01-17T15:00:00Z"
    }
  ]
}

Get Leaderboard

GET /gamification/leaderboard

Response (200):

{
  "success": true,
  "leaderboard": [
    {
      "id": "user_id",
      "name": "Alice Johnson",
      "points": 1250,
      "level": 13,
      "badges": 5,
      "profileImage": "https://example.com/alice.jpg"
    },
    {
      "id": "user_id2",
      "name": "Bob Smith",
      "points": 1100,
      "level": 12,
      "badges": 4
    }
  ]
}

Get User Rank

GET /gamification/rank

Headers: Authorization required

Response (200):

{
  "success": true,
  "rank": 42,
  "totalStudents": 1500
}

Admin Endpoints

Create Course

POST /admin/course

Headers: Authorization required (Admin only)

Request Body:

{
  "title": "Advanced React",
  "description": "Master React for production",
  "category": "Web Development",
  "level": "advanced"
}

Response (201):

{
  "success": true,
  "message": "Course created",
  "course": { ... }
}

Create Lesson

POST /admin/lesson

Headers: Authorization required (Admin only)

Request Body:

{
  "courseId": "course_id",
  "title": "Components and Props",
  "description": "Learn about React components",
  "content": "Lesson content here",
  "contentType": "video",
  "videoUrl": "https://example.com/video.mp4",
  "duration": 45,
  "order": 1
}

Response (201):

{
  "success": true,
  "message": "Lesson created",
  "lesson": { ... }
}

Create Quiz

POST /admin/quiz

Headers: Authorization required (Admin only)

Request Body:

{
  "lessonId": "lesson_id",
  "title": "Component Basics Quiz",
  "description": "Test your understanding",
  "questions": [
    {
      "question": "What is a React component?",
      "type": "multiple_choice",
      "options": ["Function", "Class", "Both", "Neither"],
      "correctAnswer": "Both",
      "explanation": "React components can be functions or classes",
      "points": 10
    }
  ],
  "passingScore": 70,
  "timeLimit": 30
}

Response (201):

{
  "success": true,
  "message": "Quiz created",
  "quiz": { ... }
}

Create Badge

POST /admin/badge

Headers: Authorization required (Admin only)

Request Body:

{
  "name": "Quiz Master",
  "description": "Complete 50 quizzes",
  "icon": "🏆",
  "requirement": "quizzes",
  "value": 50
}

Response (201):

{
  "success": true,
  "message": "Badge created",
  "badge": { ... }
}

Get All Students

GET /admin/students

Headers: Authorization required (Admin only)

Response (200):

{
  "success": true,
  "students": [
    {
      "id": "student_id",
      "name": "John Doe",
      "email": "john@example.com",
      "points": 250,
      "level": 3,
      "enrolledCourses": 5
    }
  ]
}

Get Student Performance

GET /admin/students/{studentId}/performance

Headers: Authorization required (Admin only)

Response (200):

{
  "success": true,
  "performance": {
    "student": { ... },
    "totalPoints": 250,
    "currentLevel": 3,
    "badges": 2,
    "courses": 5
  }
}

Get Dashboard Statistics

GET /admin/dashboard/stats

Headers: Authorization required (Admin only)

Response (200):

{
  "success": true,
  "stats": {
    "totalStudents": 1500,
    "totalCourses": 45,
    "totalLessons": 320,
    "totalBadges": 25
  }
}

Error Responses

400 Bad Request

{
  "success": false,
  "message": "Invalid request data"
}

401 Unauthorized

{
  "success": false,
  "message": "No token provided" or "Invalid token"
}

403 Forbidden

{
  "success": false,
  "message": "Admin access required"
}

404 Not Found

{
  "success": false,
  "message": "Resource not found"
}

500 Server Error

{
  "success": false,
  "message": "Server error"
}

Rate Limiting

Currently, there is no rate limiting implemented. This can be added using express-rate-limit middleware for production environments.

Pagination

For endpoints that return lists, implement pagination with query parameters:

  • page: Page number (default: 1)
  • limit: Items per page (default: 10)

Example: GET /admin/students?page=2&limit=20

Sorting

For list endpoints, support sorting with:

  • sortBy: Field to sort by
  • order: 'asc' or 'desc'

Example: GET /gamification/leaderboard?sortBy=points&order=desc

Last Updated

January 17, 2024