Shop Reviews

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

Short Description: The Shop Reviews API provides functionality for customers to write detailed reviews about shops and retrieve review statistics. It enables users to submit text reviews, update existing reviews, and view comprehensive review summaries with different status levels for content moderation.

Hints:

  • Review text must be between 10-1000 characters

  • Shop owners cannot review their own shops

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

  • Deleted shops cannot be reviewed

  • Reviews have different statuses: ACTIVE, HIDDEN, FLAGGED, UNDER_REVIEW

  • Only ACTIVE reviews are shown in public endpoints

  • Review moderation is handled through status changes

Endpoints

1. Create Shop Review

Purpose: Creates a review for a shop

Endpoint: POST /api/v1/shops/reviews/{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 review

Valid UUID format

Request JSON Sample:

{
  "reviewText": "Excellent service and high-quality products. The staff was very helpful and knowledgeable. Highly recommended for anyone looking for reliable electronics!"
}

Request Body Parameters:

Parameter
Type
Required
Description
Validation

reviewText

string

Yes

Review content

Min: 10, Max: 1000 characters

Response JSON Sample:

{
  "success": true,
  "message": "Review created successfully",
  "data": {
    "reviewId": "550e8400-e29b-41d4-a716-446655440006",
    "shopId": "550e8400-e29b-41d4-a716-446655440002",
    "shopName": "Tech Paradise",
    "userId": "550e8400-e29b-41d4-a716-446655440003",
    "userName": "Jane Smith",
    "reviewText": "Excellent service and high-quality products. The staff was very helpful and knowledgeable. Highly recommended for anyone looking for reliable electronics!",
    "status": "ACTIVE",
    "createdAt": "2025-09-22T14:30:00Z",
    "updatedAt": "2025-09-22T14:30:00Z",
    "isMyReview": false
  }
}

Response Fields:

Field
Description

reviewId

Unique identifier for the review

shopId

ID of the reviewed shop

shopName

Name of the reviewed shop

userId

ID of the user who created the review

userName

Full name of the user who created the review

reviewText

The review content text

status

Review status (ACTIVE, HIDDEN, FLAGGED, UNDER_REVIEW)

createdAt

Timestamp when review was created

updatedAt

Timestamp when review was last updated

isMyReview

Boolean indicating if this is the current user's review

Error Responses:

  • 400 Bad Request: Invalid review text or validation errors

  • 401 Unauthorized: Authentication required/failed

  • 404 Not Found: Shop not found

  • 409 Conflict: User has already reviewed this shop

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

  • 500 Internal Server Error: Server error

2. Update Shop Review

Purpose: Updates an existing review for a shop

Endpoint: PUT /api/v1/shops/reviews/{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:

{
  "reviewText": "Updated review: Still excellent service, but I noticed some improvements in their customer support as well! The new staff members are very professional and responsive."
}

Request Body Parameters:

Parameter
Type
Required
Description
Validation

reviewText

string

Yes

Updated review content

Min: 10, Max: 1000 characters

Response JSON Sample:

{
  "success": true,
  "message": "Review updated successfully",
  "data": {
    "reviewId": "550e8400-e29b-41d4-a716-446655440006",
    "shopId": "550e8400-e29b-41d4-a716-446655440002",
    "shopName": "Tech Paradise",
    "userId": "550e8400-e29b-41d4-a716-446655440003",
    "userName": "Jane Smith",
    "reviewText": "Updated review: Still excellent service, but I noticed some improvements in their customer support as well! The new staff members are very professional and responsive.",
    "status": "ACTIVE",
    "createdAt": "2025-09-22T14:30:00Z",
    "updatedAt": "2025-09-22T15:45:00Z",
    "isMyReview": false
  }
}

Error Responses:

  • 400 Bad Request: Invalid review text

  • 401 Unauthorized: Authentication required/failed

  • 404 Not Found: Review not found (user hasn't reviewed this shop)

  • 500 Internal Server Error: Server error

3. Delete Shop Review

Purpose: Deletes a user's review for a shop

Endpoint: DELETE /api/v1/shops/reviews/{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": "Review deleted successfully"
}

Error Responses:

  • 401 Unauthorized: Authentication required/failed

  • 404 Not Found: Review not found

  • 500 Internal Server Error: Server error

4. Get Active Reviews by Shop

Purpose: Retrieves all active reviews for a specific shop

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

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": "Shop reviews retrieved successfully",
  "data": [
    {
      "reviewId": "550e8400-e29b-41d4-a716-446655440006",
      "shopId": "550e8400-e29b-41d4-a716-446655440002",
      "shopName": "Tech Paradise",
      "userId": "550e8400-e29b-41d4-a716-446655440003",
      "userName": "Jane Smith",
      "reviewText": "Excellent service and high-quality products.",
      "status": "ACTIVE",
      "createdAt": "2025-09-22T14:30:00Z",
      "updatedAt": "2025-09-22T14:30:00Z",
      "isMyReview": true
    },
    {
      "reviewId": "550e8400-e29b-41d4-a716-446655440007",
      "shopId": "550e8400-e29b-41d4-a716-446655440002",
      "shopName": "Tech Paradise",
      "userId": "550e8400-e29b-41d4-a716-446655440008",
      "userName": "Bob Johnson",
      "reviewText": "Great selection of products and competitive prices. Fast delivery too!",
      "status": "ACTIVE",
      "createdAt": "2025-09-22T13:15:00Z",
      "updatedAt": "2025-09-22T13:15:00Z",
      "isMyReview": false
    }
  ]
}

Error Responses:

  • 401 Unauthorized: Authentication required/failed

  • 404 Not Found: Shop not found

  • 500 Internal Server Error: Server error

5. Get Active Reviews by Shop (Paginated)

Purpose: Retrieves active reviews for a shop with pagination

Endpoint: GET /api/v1/shops/reviews/{shopId}/paged

Access Level: 🌐 Public

Authentication: None

Path Parameters:

Parameter
Type
Required
Description
Validation

shopId

UUID

Yes

ID of the shop

Valid UUID format

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

Response JSON Sample:

{
  "success": true,
  "message": "Shop reviews retrieved successfully",
  "data": {
    "reviews": [
      {
        "reviewId": "550e8400-e29b-41d4-a716-446655440006",
        "shopId": "550e8400-e29b-41d4-a716-446655440002",
        "shopName": "Tech Paradise",
        "userId": "550e8400-e29b-41d4-a716-446655440003",
        "userName": "Jane Smith",
        "reviewText": "Excellent service and high-quality products.",
        "status": "ACTIVE",
        "createdAt": "2025-09-22T14:30:00Z",
        "updatedAt": "2025-09-22T14:30:00Z",
        "isMyReview": false
      }
    ],
    "currentPage": 0,
    "pageSize": 10,
    "totalElements": 15,
    "totalPages": 2,
    "hasNext": true,
    "hasPrevious": false,
    "isFirst": true,
    "isLast": false
  }
}

Error Responses:

  • 404 Not Found: Shop not found

  • 500 Internal Server Error: Server error

6. Get My Review for Shop

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

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

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 review retrieved successfully",
  "data": {
    "reviewId": "550e8400-e29b-41d4-a716-446655440006",
    "shopId": "550e8400-e29b-41d4-a716-446655440002",
    "shopName": "Tech Paradise",
    "userId": "550e8400-e29b-41d4-a716-446655440003",
    "userName": "Jane Smith",
    "reviewText": "Excellent service and high-quality products.",
    "status": "ACTIVE",
    "createdAt": "2025-09-22T14:30:00Z",
    "updatedAt": "2025-09-22T14:30:00Z",
    "isMyReview": true
  }
}

Error Responses:

  • 401 Unauthorized: Authentication required/failed

  • 404 Not Found: Review not found (user hasn't reviewed this shop)

  • 500 Internal Server Error: Server error

7. Get Shop Review Summary

Purpose: Retrieves review summary and statistics for a shop

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

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 review summary retrieved successfully",
  "data": {
    "shopId": "550e8400-e29b-41d4-a716-446655440002",
    "shopName": "Tech Paradise",
    "totalReviews": 18,
    "activeReviews": 15,
    "hiddenReviews": 2,
    "flaggedReviews": 1
  }
}

Response Fields:

Field
Description

shopId

ID of the shop

shopName

Name of the shop

totalReviews

Total number of reviews (all statuses except deleted)

activeReviews

Number of active/visible reviews

hiddenReviews

Number of hidden reviews (by admin)

flaggedReviews

Number of flagged reviews (reported/under moderation)

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)

  • Pagination: Uses 1-based indexing (page=1 for first page)

  • Boolean Values: Use true/false (lowercase)

Review Status Types

  • ACTIVE: Review is visible to all users

  • HIDDEN: Review is hidden by admin but not deleted

  • FLAGGED: Review has been reported and needs moderation

  • UNDER_REVIEW: Review is being reviewed by moderators

Business Rules

  • Review Length: Review text must be between 10 and 1000 characters

  • One Review Per User: Each user can only review a shop once - use update to change existing review

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

  • Deleted Shop Restriction: Deleted shops cannot receive new reviews

  • Content Moderation: Reviews can be moderated through status changes

  • Public Visibility: Only ACTIVE reviews are shown in public endpoints

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

PreviousShop RatingsNextProduct Management Service

Last updated