Shop Ratings

Author: NextGate Development Team, Backend Engineers Last Updated: 2025-09-22 Version: v1.0

Short Description: The Shop Ratings API provides functionality for customers to rate shops and retrieve rating statistics. It enables users to submit ratings (1-5 stars), update existing ratings, and view comprehensive rating summaries including average ratings and distribution analytics.

Hints:

  • Rating values must be between 1-5 (inclusive)

  • Shop owners cannot rate their own shops

  • Each user can only rate a shop once (use update to change rating)

  • Deleted shops cannot be rated

  • All rating endpoints require authentication except for viewing ratings and summaries

  • Rating statistics are calculated in real-time

Endpoints

1. Create Shop Rating

Purpose: Creates a rating for a shop

Endpoint: POST /api/v1/shops/ratings/{shopId}

Access Level: 🔒 Protected (Requires authentication)

Authentication: Bearer Token

Request Headers:

Header
Type
Required
Description

Authorization

string

Yes

Bearer token for authentication

Content-Type

string

Yes

application/json

Path Parameters:

Parameter
Type
Required
Description
Validation

shopId

UUID

Yes

ID of the shop to rate

Valid UUID format

Request JSON Sample:

{
  "ratingValue": 5
}

Request Body Parameters:

Parameter
Type
Required
Description
Validation

ratingValue

integer

Yes

Rating value

Min: 1, Max: 5

Response JSON Sample:

{
  "success": true,
  "message": "Rating created successfully",
  "data": {
    "ratingId": "550e8400-e29b-41d4-a716-446655440005",
    "shopId": "550e8400-e29b-41d4-a716-446655440002",
    "shopName": "Tech Paradise",
    "userId": "550e8400-e29b-41d4-a716-446655440003",
    "userName": "Jane Smith",
    "ratingValue": 5,
    "createdAt": "2025-09-22T14:30:00Z",
    "updatedAt": "2025-09-22T14:30:00Z"
  }
}

Response Fields:

Field
Description

ratingId

Unique identifier for the rating

shopId

ID of the rated shop

shopName

Name of the rated shop

userId

ID of the user who created the rating

userName

Full name of the user who created the rating

ratingValue

The rating value (1-5)

createdAt

Timestamp when rating was created

updatedAt

Timestamp when rating was last updated

Error Responses:

  • 400 Bad Request: Invalid rating value (not between 1-5)

  • 401 Unauthorized: Authentication required/failed

  • 404 Not Found: Shop not found

  • 409 Conflict: User has already rated this shop

  • 422 Unprocessable Entity: Shop owner cannot rate own shop or shop is deleted

  • 500 Internal Server Error: Server error

2. Update Shop Rating

Purpose: Updates an existing rating for a shop

Endpoint: PUT /api/v1/shops/ratings/{shopId}

Access Level: 🔒 Protected (Requires authentication)

Authentication: Bearer Token

Request Headers:

Header
Type
Required
Description

Authorization

string

Yes

Bearer token for authentication

Content-Type

string

Yes

application/json

Path Parameters:

Parameter
Type
Required
Description
Validation

shopId

UUID

Yes

ID of the shop

Valid UUID format

Request JSON Sample:

{
  "ratingValue": 4
}

Request Body Parameters:

Parameter
Type
Required
Description
Validation

ratingValue

integer

Yes

Updated rating value

Min: 1, Max: 5

Response JSON Sample:

{
  "success": true,
  "message": "Rating updated successfully",
  "data": {
    "ratingId": "550e8400-e29b-41d4-a716-446655440005",
    "shopId": "550e8400-e29b-41d4-a716-446655440002",
    "shopName": "Tech Paradise",
    "userId": "550e8400-e29b-41d4-a716-446655440003",
    "userName": "Jane Smith",
    "ratingValue": 4,
    "createdAt": "2025-09-22T14:30:00Z",
    "updatedAt": "2025-09-22T15:45:00Z"
  }
}

Error Responses:

  • 400 Bad Request: Invalid rating value

  • 401 Unauthorized: Authentication required/failed

  • 404 Not Found: Rating not found (user hasn't rated this shop)

  • 500 Internal Server Error: Server error

3. Delete Shop Rating

Purpose: Deletes a user's rating for a shop

Endpoint: DELETE /api/v1/shops/ratings/{shopId}

Access Level: 🔒 Protected (Requires authentication)

Authentication: Bearer Token

Request Headers:

Header
Type
Required
Description

Authorization

string

Yes

Bearer token for authentication

Path Parameters:

Parameter
Type
Required
Description
Validation

shopId

UUID

Yes

ID of the shop

Valid UUID format

Response JSON Sample:

{
  "success": true,
  "message": "Rating deleted successfully"
}

Error Responses:

  • 401 Unauthorized: Authentication required/failed

  • 404 Not Found: Rating not found

  • 500 Internal Server Error: Server error

4. Get Shop Ratings

Purpose: Retrieves all ratings for a specific shop

Endpoint: GET /api/v1/shops/ratings/{shopId}

Access Level: 🌐 Public

Authentication: None

Path Parameters:

Parameter
Type
Required
Description
Validation

shopId

UUID

Yes

ID of the shop

Valid UUID format

Response JSON Sample:

{
  "success": true,
  "message": "Shop ratings retrieved successfully",
  "data": [
    {
      "ratingId": "550e8400-e29b-41d4-a716-446655440005",
      "shopId": "550e8400-e29b-41d4-a716-446655440002",
      "shopName": "Tech Paradise",
      "userId": "550e8400-e29b-41d4-a716-446655440003",
      "userName": "Jane Smith",
      "ratingValue": 5,
      "createdAt": "2025-09-22T14:30:00Z",
      "updatedAt": "2025-09-22T14:30:00Z"
    },
    {
      "ratingId": "550e8400-e29b-41d4-a716-446655440006",
      "shopId": "550e8400-e29b-41d4-a716-446655440002",
      "shopName": "Tech Paradise",
      "userId": "550e8400-e29b-41d4-a716-446655440007",
      "userName": "John Doe",
      "ratingValue": 4,
      "createdAt": "2025-09-22T13:15:00Z",
      "updatedAt": "2025-09-22T13:15:00Z"
    }
  ]
}

Error Responses:

  • 404 Not Found: Shop not found

  • 500 Internal Server Error: Server error

5. Get My Rating for Shop

Purpose: Retrieves the authenticated user's rating for a specific shop

Endpoint: GET /api/v1/shops/ratings/{shopId}/my-rating

Access Level: 🔒 Protected (Requires authentication)

Authentication: Bearer Token

Request Headers:

Header
Type
Required
Description

Authorization

string

Yes

Bearer token for authentication

Path Parameters:

Parameter
Type
Required
Description
Validation

shopId

UUID

Yes

ID of the shop

Valid UUID format

Response JSON Sample:

{
  "success": true,
  "message": "Your rating retrieved successfully",
  "data": {
    "ratingId": "550e8400-e29b-41d4-a716-446655440005",
    "shopId": "550e8400-e29b-41d4-a716-446655440002",
    "shopName": "Tech Paradise",
    "userId": "550e8400-e29b-41d4-a716-446655440003",
    "userName": "Jane Smith",
    "ratingValue": 5,
    "createdAt": "2025-09-22T14:30:00Z",
    "updatedAt": "2025-09-22T14:30:00Z"
  }
}

Error Responses:

  • 401 Unauthorized: Authentication required/failed

  • 404 Not Found: Rating not found (user hasn't rated this shop)

  • 500 Internal Server Error: Server error

6. Get Shop Rating Summary

Purpose: Retrieves rating summary and distribution for a shop

Endpoint: GET /api/v1/shops/ratings/{shopId}/summary

Access Level: 🌐 Public

Authentication: None

Path Parameters:

Parameter
Type
Required
Description
Validation

shopId

UUID

Yes

ID of the shop

Valid UUID format

Response JSON Sample:

{
  "success": true,
  "message": "Shop rating summary retrieved successfully",
  "data": {
    "shopId": "550e8400-e29b-41d4-a716-446655440002",
    "shopName": "Tech Paradise",
    "averageRating": 4.5,
    "totalRatings": 23,
    "ratingDistribution": {
      "1": 1,
      "2": 0,
      "3": 2,
      "4": 5,
      "5": 15
    }
  }
}

Response Fields:

Field
Description

shopId

ID of the shop

shopName

Name of the shop

averageRating

Average rating value (rounded to 1 decimal place)

totalRatings

Total number of ratings received

ratingDistribution

Count of ratings for each value (1-5 stars)

Error Responses:

  • 404 Not Found: Shop not found

  • 500 Internal Server Error: Server error

Quick Reference Guide

Common HTTP Status Codes

  • 200 OK: Successful GET/PUT/PATCH request

  • 201 Created: Successful POST request

  • 204 No Content: Successful DELETE request

  • 400 Bad Request: Invalid request data

  • 401 Unauthorized: Authentication required/failed

  • 403 Forbidden: Insufficient permissions

  • 404 Not Found: Resource not found

  • 409 Conflict: Resource already exists

  • 422 Unprocessable Entity: Validation errors

  • 429 Too Many Requests: Rate limit exceeded

  • 500 Internal Server Error: Server error

Authentication Types

  • Bearer Token: Include Authorization: Bearer your_token in headers

  • None: No authentication required

Data Format Standards

  • Dates: Use ISO 8601 format (2025-09-22T14:30:00Z)

  • UUIDs: Use standard UUID format (550e8400-e29b-41d4-a716-446655440000)

  • Rating Values: Integer values from 1 to 5 (inclusive)

  • Decimal Precision: Average ratings rounded to 1 decimal place

Business Rules

  • Rating Range: All rating values must be between 1 and 5 (inclusive)

  • One Rating Per User: Each user can only rate a shop once - use update to change existing rating

  • Shop Owner Restriction: Shop owners cannot rate their own shops

  • Deleted Shop Restriction: Deleted shops cannot receive new ratings

  • Real-time Calculation: Rating summaries and averages are calculated in real-time

  • Soft Delete: Deleted ratings are marked as deleted but not physically removed from database

PreviousShop ManagementNextShop Reviews

Last updated