Course API Integration Guide

This document provides frontend developers with comprehensive instructions on how to integrate the Course API endpoints into their applications.

Base URL

All endpoints are prefixed with /api/courses

Authentication

• Some endpoints require authentication (JWT token in Authorization header)
• Optional endpoints work with or without authentication
• Token format: Bearer

Endpoints

1. Search Courses

Endpoint: GET /api/courses/search

Description: Search for courses by query string

Authentication: Optional

Request Parameters:

• query (required): Search term

Example Request:

fetch('/api/courses/search?query=javascript', {
  headers: {
    'Authorization': 'Bearer your-token-here' // optional
  }
})
.then(response => response.json())
.then(data => console.log(data));

Response Structure:

{
  success: boolean;
  message?: string;
  data?: {
    id: string;           // Course ID
    title: string;        // Course title
    description: string;  // Full description
    shortDescription: string; // Brief description
    provider: string;     // e.g. "Udemy", "Coursera"
    url: string;          // Course URL
    categories: string[]; // Course categories
    isFree: boolean;      // Free/paid status
    imageUrl?: string;    // Course image URL
    isBookmarked?: boolean; // Only present if user authenticated
  }[];
}

2. Get Featured Courses

Endpoint: GET /api/courses/featured

Description: Get featured/popular courses

Authentication: Optional

Example Request:

fetch('/api/courses/featured', {
  headers: {
    'Authorization': 'Bearer your-token-here' // optional
  }
})

Response Structure: Same as search endpoint

3. Get Course Details

Endpoint: GET /api/courses/course/:id

Description: Get detailed information about a specific course

Authentication: Optional

Example Request:

fetch('/api/courses/course/507f1f77bcf86cd799439011', {
  headers: {
    'Authorization': 'Bearer your-token-here' // optional
  }
})

Response Structure: Same as search endpoint (single course)

4. Get User's Courses

Endpoint: GET /api/courses/user/courses

Description: Get all courses bookmarked by the authenticated user

Authentication: Required

Example Request:

fetch('/api/courses/user/courses', {
  headers: {
    'Authorization': 'Bearer your-token-here'
  }
})

Response Structure: Same as search endpoint (always includes isBookmarked)

5. Bookmark/Unbookmark Course

Endpoint: POST /api/courses/:courseId/bookmark

Description: Bookmark or unbookmark a course

Authentication: Required

Request Body:

{
  bookmark: boolean; // true to bookmark, false to unbookmark
}

Example Request:

fetch('/api/courses/507f1f77bcf86cd799439011/bookmark', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-token-here'
  },
  body: JSON.stringify({ bookmark: true })
})

Response Structure:

{
  success: boolean;
  message?: string;
  data?: {
    isBookmarked: boolean; // New bookmark status
  };
}

Error Handling

Handle potential errors by checking:

1. response.success - false indicates an error
2. HTTP status codes:
   • 400: Bad request
   • 401: Unauthorized (when authentication is required)
   • 404: Not found
   • 500: Server error

Best Practices

1. Authentication:

   • Store JWT securely (httpOnly cookies recommended)
   • Include token in headers for authenticated endpoints

2. Pagination:

   • Currently not implemented but can be added if needed

3. Caching:

   • Consider caching course data client-side to reduce API calls

4. Error States:

   • Always handle loading and error states in your UI

5. Rate Limiting:

   • Be mindful of API rate limits (not currently implemented but may be added)