Skip to main content

Shop Rating

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2025-09-23
Version: v1.0

Base URL: https://api.nextgate.com/api/v1

Short Description: The Shop Rating API allows users to rate shops on a 1-5 scale, manage their ratings, and retrieve rating summaries. Users can create, update, and delete their own ratings while viewing comprehensive rating analytics for shops.

Hints:

  • All rating operations require Bearer token authentication
  • Users can only have one rating per shop (use update to change)
  • Shop owners cannot rate their own shops
  • Rating values must be between 1-5 (integer)
  • Deleted shops cannot be rated

Standard Response Format

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-09-23T10:30:45",
  "data": "Error description"
}

Endpoints

1. Create Rating

Purpose: Creates a new rating for a shop (one rating per user per shop)

Endpoint: POST {base_url}/shops/ratings/{shopId}

Access Level: 🔒 Protected (Requires Bearer Token)

Authentication: Bearer Token

Path Parameters:

Parameter Type Required Description Validation
shopId UUID Yes Unique identifier of the shop Must be valid UUID

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authenticated user
Content-Type string Yes application/json

Request JSON Sample:

{
  "ratingValue": 5
}

Request Body Parameters:

Parameter Type Required Description Validation
ratingValue integer Yes Rating value Min: 1, Max: 5

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Rating created successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "ratingId": "rating-123e4567-e89b-12d3-a456-426614174000",
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Restaurant",
    "userId": "456e7890-e89b-12d3-a456-426614174001",
    "userName": "John Doe",
    "ratingValue": 5,
    "createdAt": "2025-09-23T10:30:45",
    "updatedAt": "2025-09-23T10:30:45"
  }
}

Error Response Examples:

Shop Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Shop not found",
  "action_time": "2025-09-23T10:30:45",
  "data": "Shop not found"
}

Rating Already Exists (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "You have already rated this shop. Use update to change your rating.",
  "action_time": "2025-09-23T10:30:45",
  "data": "You have already rated this shop. Use update to change your rating."
}

Shop Owner Cannot Rate Own Shop (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Shop owners cannot rate their own shops",
  "action_time": "2025-09-23T10:30:45",
  "data": "Shop owners cannot rate their own shops"
}

2. Update Rating

Purpose: Updates user's existing rating for a shop

Endpoint: PUT {base_url}/shops/ratings/{shopId}

Access Level: 🔒 Protected (Rating Owner Only)

Authentication: Bearer Token

Path Parameters:

Parameter Type Required Description Validation
shopId UUID Yes Unique identifier of the shop Must be valid UUID

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authenticated user
Content-Type string Yes application/json

Request JSON Sample:

{
  "ratingValue": 4
}

Request Body Parameters:

Parameter Type Required Description Validation
ratingValue integer Yes Updated rating value Min: 1, Max: 5

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Rating updated successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "ratingId": "rating-123e4567-e89b-12d3-a456-426614174000",
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Restaurant",
    "userId": "456e7890-e89b-12d3-a456-426614174001",
    "userName": "John Doe",
    "ratingValue": 4,
    "createdAt": "2025-09-23T10:30:45",
    "updatedAt": "2025-09-23T11:15:30"
  }
}

Error Response Examples:

Rating Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Rating not found. Create a rating first.",
  "action_time": "2025-09-23T10:30:45",
  "data": "Rating not found. Create a rating first."
}

3. Delete Rating

Purpose: Soft deletes user's rating for a shop

Endpoint: DELETE {base_url}/shops/ratings/{shopId}

Access Level: 🔒 Protected (Rating Owner Only)

Authentication: Bearer Token

Path Parameters:

Parameter Type Required Description Validation
shopId UUID Yes Unique identifier of the shop Must be valid UUID

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authenticated user

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Rating deleted successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": null
}

4. Get All Ratings for Shop

Purpose: Retrieves all ratings for a specific shop

Endpoint: GET {base_url}/shops/ratings/{shopId}

Access Level: 🌐 Public (No authentication required)

Authentication: None

Path Parameters:

Parameter Type Required Description Validation
shopId UUID Yes Unique identifier of the shop Must be valid UUID

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop ratings retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": [
    {
      "ratingId": "rating-123e4567-e89b-12d3-a456-426614174000",
      "shopId": "123e4567-e89b-12d3-a456-426614174000",
      "shopName": "Mama Lucy's Restaurant",
      "userId": "456e7890-e89b-12d3-a456-426614174001",
      "userName": "John Doe",
      "ratingValue": 5,
      "createdAt": "2025-09-23T10:30:45",
      "updatedAt": "2025-09-23T10:30:45"
    },
    {
      "ratingId": "rating-456e7890-e89b-12d3-a456-426614174001",
      "shopId": "123e4567-e89b-12d3-a456-426614174000",
      "shopName": "Mama Lucy's Restaurant",
      "userId": "789e0123-e89b-12d3-a456-426614174002",
      "userName": "Jane Smith",
      "ratingValue": 4,
      "createdAt": "2025-09-22T15:20:30",
      "updatedAt": "2025-09-22T15:20:30"
    }
  ]
}

5. Get My Rating for Shop

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

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

Access Level: 🔒 Protected (Authenticated User Only)

Authentication: Bearer Token

Path Parameters:

Parameter Type Required Description Validation
shopId UUID Yes Unique identifier of the shop Must be valid UUID

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authenticated user

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Your rating retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "ratingId": "rating-123e4567-e89b-12d3-a456-426614174000",
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Restaurant",
    "userId": "456e7890-e89b-12d3-a456-426614174001",
    "userName": "John Doe",
    "ratingValue": 5,
    "createdAt": "2025-09-23T10:30:45",
    "updatedAt": "2025-09-23T10:30:45"
  }
}

Error Response Examples:

No Rating Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "You have not rated this shop yet",
  "action_time": "2025-09-23T10:30:45",
  "data": "You have not rated this shop yet"
}

6. Get Shop Rating Summary

Purpose: Retrieves comprehensive rating statistics for a shop including distribution and analytics

Endpoint: GET {base_url}/shops/ratings/{shopId}/summary

Access Level: 🌐 Public (No authentication required)

Authentication: None

Path Parameters:

Parameter Type Required Description Validation
shopId UUID Yes Unique identifier of the shop Must be valid UUID

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop rating summary retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Restaurant",
    "averageRating": 4.3,
    "totalRatings": 25,
    "ratingDistribution": {
      "1": 1,
      "2": 2,
      "3": 5,
      "4": 7,
      "5": 10
    }
  }
}

Success Response Fields:

Field Description
shopId Unique identifier of the shop
shopName Name of the shop
averageRating Average rating (rounded to 1 decimal place)
totalRatings Total number of active ratings
ratingDistribution Count of ratings by value (1-5 stars)

Business Rules

Rating Creation Rules

  • Users must be authenticated to create ratings
  • One rating per user per shop (use update to modify)
  • Shop owners cannot rate their own shops
  • Cannot rate deleted shops
  • Rating value must be integer between 1-5

Rating Update Rules

  • Only rating owner can update their rating
  • Must have existing rating to update
  • Same validation rules apply as creation

Rating Deletion Rules

  • Only rating owner can delete their rating
  • Soft delete (sets isDeleted = true)
  • Deleted ratings don't count in summaries

Summary Calculation Rules

  • Average rating rounded to 1 decimal place
  • Only non-deleted ratings counted
  • Distribution shows count for each rating value (1-5)
  • Empty shops show 0.0 average and empty distribution

Error Types

Standard Error Codes

  • 400 BAD_REQUEST: Business logic violations, already exists
  • 401 UNAUTHORIZED: Invalid/missing token
  • 404 NOT_FOUND: Shop/rating not found, user not authenticated
  • 422 UNPROCESSABLE_ENTITY: Validation errors

Validation Error Example

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "ratingValue": "Rating must be between 1 and 5"
  }
}

No comments to display

Back to top