Shop Review

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 Review API allows users to write, manage, and retrieve text reviews for shops. Users can create, update, and delete their reviews while viewing comprehensive review analytics and filtering by status.

Hints:

All review operations require Bearer token authentication
Users can only have one review per shop (use update to change)
Shop owners cannot review their own shops
Review text must be 10-1000 characters
Reviews have status: ACTIVE, HIDDEN, FLAGGED, UNDER_REVIEW

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 Review

Purpose: Creates a new text review for a shop

Endpoint: POST {base_url}/shops/reviews/{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:

{
  "reviewText": "Amazing food and excellent service! The staff was very friendly and the atmosphere was perfect for a family dinner. Highly recommend the local dishes."
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
reviewText	string	Yes	Review content	Min: 10, Max: 1000 characters

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Review created successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "reviewId": "review-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",
    "reviewText": "Amazing food and excellent service! The staff was very friendly and the atmosphere was perfect for a family dinner. Highly recommend the local dishes.",
    "status": "ACTIVE",
    "createdAt": "2025-09-23T10:30:45",
    "updatedAt": "2025-09-23T10:30:45",
    "isMyReview": false
  }
}

Error Response Examples:

Review Already Exists (400):

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

Shop Owner Cannot Review Own Shop (400):

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

2. Update Review

Purpose: Updates user's existing review for a shop

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

Access Level: 🔒 Protected (Review 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 JSON Sample:

{
  "reviewText": "Updated review: Still amazing food but service could be improved. The local dishes are definitely worth trying and the prices are reasonable."
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
reviewText	string	Yes	Updated review content	Min: 10, Max: 1000 characters

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Review updated successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "reviewId": "review-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",
    "reviewText": "Updated review: Still amazing food but service could be improved. The local dishes are definitely worth trying and the prices are reasonable.",
    "status": "ACTIVE",
    "createdAt": "2025-09-23T10:30:45",
    "updatedAt": "2025-09-23T11:15:30",
    "isMyReview": false
  }
}

Error Response Examples:

Review Not Found (404):

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

3. Delete Review

Purpose: Soft deletes user's review for a shop

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

Access Level: 🔒 Protected (Review Owner Only)

Authentication: Bearer Token

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": "Review deleted successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": null
}

4. Get Active Reviews for Shop

Purpose: Retrieves all active reviews for a specific shop

Endpoint: GET {base_url}/shops/reviews/{shopId}/active-reviews-by-shop

Access Level: 🔒 Protected (Requires Authentication to show isMyReview flag)

Authentication: Bearer Token

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 reviews retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": [
    {
      "reviewId": "review-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",
      "reviewText": "Amazing food and excellent service!",
      "status": "ACTIVE",
      "createdAt": "2025-09-23T10:30:45",
      "updatedAt": "2025-09-23T10:30:45",
      "isMyReview": true
    },
    {
      "reviewId": "review-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",
      "reviewText": "Great local dishes, very authentic taste!",
      "status": "ACTIVE",
      "createdAt": "2025-09-22T15:20:30",
      "updatedAt": "2025-09-22T15:20:30",
      "isMyReview": false
    }
  ]
}

5. Get Active Reviews for Shop (Paginated)

Purpose: Retrieves active reviews for a shop with pagination

Endpoint: GET {base_url}/shops/reviews/{shopId}/paged

Access Level: 🔒 Protected (Requires Authentication)

Authentication: Bearer Token

Path Parameters:

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

Query Parameters:

Parameter	Type	Required	Description	Validation	Default
page	integer	No	Page number (1-based)	Min: 1	1
size	integer	No	Number of items per page	Min: 1, Max: 100	10

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Shop reviews retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "reviews": [
      {
        "reviewId": "review-123e4567-e89b-12d3-a456-426614174000",
        "shopId": "123e4567-e89b-12d3-a456-426614174000",
        "shopName": "Mama Lucy's Restaurant",
        "userName": "John Doe",
        "reviewText": "Amazing food and excellent service!",
        "status": "ACTIVE",
        "createdAt": "2025-09-23T10:30:45",
        "isMyReview": true
      }
    ],
    "currentPage": 1,
    "pageSize": 10,
    "totalElements": 25,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": false
  }
}

6. Get My Review for Shop

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

Endpoint: GET {base_url}/shops/reviews/{shopId}/my-review

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

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Your review retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "reviewId": "review-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",
    "reviewText": "Amazing food and excellent service!",
    "status": "ACTIVE",
    "createdAt": "2025-09-23T10:30:45",
    "updatedAt": "2025-09-23T10:30:45",
    "isMyReview": false
  }
}

Success Response (No Review Found):

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

7. Get Shop Review Summary

Purpose: Retrieves comprehensive review statistics for a shop by status

Endpoint: GET {base_url}/shops/reviews/{shopId}/summary-shop-review

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 review summary retrieved successfully",
  "action_time": "2025-09-23T10:30:45",
  "data": {
    "shopId": "123e4567-e89b-12d3-a456-426614174000",
    "shopName": "Mama Lucy's Restaurant",
    "totalReviews": 25,
    "activeReviews": 22,
    "hiddenReviews": 2,
    "flaggedReviews": 1
  }
}

Success Response Fields:

Field	Description
shopId	Unique identifier of the shop
shopName	Name of the shop
totalReviews	Total number of reviews (all statuses)
activeReviews	Number of active/visible reviews
hiddenReviews	Number of hidden reviews
flaggedReviews	Number of flagged reviews

Data Models

Review Status Enum

Value	Description
`ACTIVE`	Review is visible and active
`HIDDEN`	Review is hidden from public view
`FLAGGED`	Review has been flagged for review
`UNDER_REVIEW`	Review is under admin review

Business Rules

Review Creation Rules

Users must be authenticated to create reviews
One review per user per shop (use update to modify)
Shop owners cannot review their own shops
Cannot review deleted shops
Review text must be 10-1000 characters
New reviews default to ACTIVE status

Review Update Rules

Only review owner can update their review
Must have existing review to update
Same validation rules apply as creation
Updates set new updatedAt timestamp

Review Deletion Rules

Only review owner can delete their review
Soft delete (sets isDeleted = true)
Deleted reviews don't appear in listings or counts

Review Status Rules

Only ACTIVE reviews appear in public listings
All statuses count in summary statistics
isMyReview flag shows if review belongs to current user

Error Types

Standard Error Codes

400 BAD_REQUEST: Business logic violations, already exists
401 UNAUTHORIZED: Invalid/missing token
404 NOT_FOUND: Shop/review 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": {
    "reviewText": "Review must be between 10 and 1000 characters"
  }
}

Shop Categories Management

Shop Management

Shop Rating

Shop Review

Product Management

Cart Management

Wishlist Management

Wallet

Transaction History

Installment Purchase - Customer Endpoints

Installment Purchase - Public & Plan Endpoints

Installment Plan Management - Admin/Shop Endpoints

Shop Review

Standard Response Format

Success Response Structure

Error Response Structure

Endpoints

1. Create Review

2. Update Review

3. Delete Review

4. Get Active Reviews for Shop

5. Get Active Reviews for Shop (Paginated)

6. Get My Review for Shop

7. Get Shop Review Summary

Data Models

Review Status Enum

Business Rules

Review Creation Rules

Review Update Rules

Review Deletion Rules

Review Status Rules

Error Types

Standard Error Codes

Validation Error Example