Add Course Rating

Submit a rating and review for a completed course

POST /api/user/add-rating

Add Course Rating

cURL

curl --request POST \
  --url https://api.example.com/api/user/add-rating \
  --header 'Content-Type: application/json' \
  --data '
{
  "courseId": "<string>",
  "rating": 123,
  "review": "<string>"
}
'

200

{
  "success": true,
  "message": "<string>",
  "data": {
    "courseId": "<string>",
    "rating": 123,
    "review": "<string>",
    "averageRating": 123,
    "totalRatings": 123
  }
}

Overview

Allows students to rate a course they have completed. Ratings are stored with the user’s enrollment record and displayed on course detail pages.

Authentication

Requires Clerk authentication. The user must be enrolled in the course.

Request Body

courseId · string · required

The MongoDB ObjectId of the course to rate

rating · number · required

Rating value between 1-5 stars

Must be an integer: 1, 2, 3, 4, or 5

review · string

Optional text review/comment about the course

Maximum length: 500 characters

Response

success · boolean

Indicates whether the rating was saved successfully

message · string

Confirmation message

data · object

The updated course rating information

Show data

courseId · string

The course that was rated

rating · number

The submitted rating (1-5)

review · string

The submitted review text

averageRating · number

Updated average rating for the course

totalRatings · number

Total number of ratings the course has received

Request Example

{
  "courseId": "65f3a1b2c3d4e5f6g7h8i9j0",
  "rating": 5,
  "review": "Excellent course! The instructor explained complex concepts clearly and the hands-on projects were very helpful."
}

Response Example

{
  "success": true,
  "message": "Rating submitted successfully",
  "data": {
    "courseId": "65f3a1b2c3d4e5f6g7h8i9j0",
    "rating": 5,
    "review": "Excellent course! The instructor explained...",
    "averageRating": 4.7,
    "totalRatings": 128
  }
}

Error Responses

400 Bad Request

• Missing required fields
• Invalid rating value (not 1-5)
• Review text exceeds 500 characters

404 Not Found

• User is not enrolled in the course
• Course does not exist

403 Forbidden

• User has not completed the course yet
• Ratings may be restricted to completed courses only

Implementation Details

Rating Storage

Ratings are stored in the User model’s courseRatings array:

courseRatings: [
  {
    courseId: ObjectId,
    rating: Number,      // 1-5
    review: String,
    createdAt: Date
  }
]

Rating Update Rules

• Users can update their rating for a course by submitting again
• The most recent rating replaces any previous rating
• Average rating is recalculated for the course after each submission

Code Examples

JavaScript (Fetch)

const response = await fetch(`${BACKEND_URL}/api/user/add-rating`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${clerkToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    courseId: '65f3a1b2c3d4e5f6g7h8i9j0',
    rating: 5,
    review: 'Great course with excellent content!'
  })
});

const data = await response.json();
console.log(`Average rating: ${data.data.averageRating}`);

Use Cases

1. Collect student feedback on course quality
2. Display ratings on course pages to help prospective students
3. Calculate average ratings to rank courses
4. Identify top-rated courses for marketing purposes

Related Endpoints

• Get Course - View course with ratings
• Get Enrolled Courses - See which courses you can rate