Skip to content

API_DOCS.md

Latest commit

 

History

History
381 lines (335 loc) · 6.08 KB

API_DOCS.md

File metadata and controls

381 lines (335 loc) · 6.08 KB
Raw

📚 API Documentation

Base URL

http://localhost:3000/api

Response Format

All responses follow the JSend specification:

Success Response

{
  "status": "success",
  "data": { /* Application data */ }
}

Error Response

{
  "status": "fail|error",
  "data": { /* Error details */ },
  "message": "Error description"
}

Authentication

Register New User

  • Endpoint: POST /auth/register
  • Description: Create a new user account
  • Auth Required: No

Request Body:

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "MyPassword123!",
  "age": 25
}

Success Response (201):

{
  "status": "success",
  "data": {
    "user": {
      "id": "64abc123...",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "user"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Login User

  • Endpoint: POST /auth/login
  • Description: Authenticate existing user
  • Auth Required: No

Request Body:

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

Success Response (200):

{
  "status": "success",
  "data": {
    "user": {
      "id": "64abc123...",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "user"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Logout User

  • Endpoint: POST /auth/logout
  • Description: Logout user (client-side token removal)
  • Auth Required: No

Success Response (200):

{
  "status": "success",
  "data": {
    "message": "Logged out successfully"
  }
}

User Profile

Get User Profile

  • Endpoint: GET /profile/me
  • Description: Get current user's profile
  • Auth Required: Yes

Headers:

Authorization: Bearer <jwt_token>

Success Response (200):

{
  "status": "success",
  "data": {
    "user": {
      "_id": "64abc123...",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "user",
      "age": 25,
      "enrolledCourses": [],
      "createdAt": "2025-09-26T..."
    }
  }
}

Update User Profile

  • Endpoint: PATCH /profile/me
  • Description: Update current user's profile
  • Auth Required: Yes

Headers:

Authorization: Bearer <jwt_token>

Request Body:

{
  "name": "Updated Name",
  "email": "newemail@example.com"
}

Success Response (200):

{
  "status": "success",
  "data": {
    "user": {
      "_id": "64abc123...",
      "name": "Updated Name",
      "email": "newemail@example.com",
      "role": "user",
      "age": 25
    }
  }
}

Delete User Account

  • Endpoint: DELETE /profile/me
  • Description: Delete current user's account
  • Auth Required: Yes

Headers:

Authorization: Bearer <jwt_token>

Request Body (Optional):

{
  "password": "MyPassword123!"
}

Success Response (200):

{
  "status": "success",
  "data": {
    "message": "Account deleted successfully"
  }
}

Course Management

Get All Courses

  • Endpoint: GET /courses
  • Description: Get paginated list of courses
  • Auth Required: No

Query Parameters:

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

Success Response (200):

{
  "status": "success",
  "data": {
    "courses": [
      {
        "_id": "64def456...",
        "title": "Node.js Fundamentals",
        "price": 99,
        "instructor": "Jane Smith",
        "level": "beginner",
        "duration": 20
      }
    ],
    "pagination": {
      "currentPage": 1,
      "totalPages": 5,
      "totalItems": 50
    }
  }
}

Get Course by ID

  • Endpoint: GET /courses/:courseId
  • Description: Get specific course details
  • Auth Required: No

Success Response (200):

{
  "status": "success",
  "data": {
    "course": {
      "_id": "64def456...",
      "title": "Node.js Fundamentals",
      "price": 99,
      "description": "Learn Node.js from scratch",
      "instructor": "Jane Smith",
      "level": "beginner",
      "duration": 20,
      "createdAt": "2025-09-26T..."
    }
  }
}

Create Course

  • Endpoint: POST /courses
  • Description: Create a new course
  • Auth Required: Yes

Headers:

Authorization: Bearer <jwt_token>

Request Body:

{
  "title": "Advanced JavaScript",
  "price": 149,
  "description": "Master advanced JavaScript concepts",
  "instructor": "John Developer",
  "level": "advanced",
  "duration": 30
}

Success Response (201):

{
  "status": "success",
  "data": {
    "course": {
      "_id": "64def789...",
      "title": "Advanced JavaScript",
      "price": 149,
      "description": "Master advanced JavaScript concepts",
      "instructor": "John Developer",
      "level": "advanced",
      "duration": 30,
      "createdAt": "2025-09-26T..."
    }
  }
}

Update Course

  • Endpoint: PATCH /courses/:courseId
  • Description: Update existing course
  • Auth Required: Yes

Headers:

Authorization: Bearer <jwt_token>

Request Body:

{
  "title": "Updated Course Title",
  "price": 199
}

Delete Course

  • Endpoint: DELETE /courses/:courseId
  • Description: Delete a course
  • Auth Required: Yes

Headers:

Authorization: Bearer <jwt_token>

Success Response (200):

{
  "status": "success",
  "data": {
    "course": {
      "_id": "64def456...",
      "title": "Deleted Course"
    }
  }
}

Error Responses

Validation Error (400)

{
  "status": "fail",
  "data": {
    "validation": [
      {
        "field": "email",
        "message": "Please provide a valid email"
      }
    ]
  }
}

Authentication Error (401)

{
  "status": "fail",
  "data": {
    "auth": "Access token required"
  }
}

Not Found Error (404)

{
  "status": "fail",
  "data": {
    "message": "Route /api/invalid-route not found"
  }
}

Server Error (500)

{
  "status": "error",
  "message": "Internal server error",
  "stack": "Error details..."
}