Product Reviews

​

List Product Reviews

GET /api/v1/products/{product_id}/reviews/

​

Authentication

​

Path Parameters

​

Response

​

Request Example

curl -X GET "https://api.example.com/api/v1/products/1/reviews/" \
  -H "Accept: application/json"

​

Response Example

[
  {
    "id": 15,
    "user": "john_doe",
    "review_text": "Excellent sound quality and comfortable for long listening sessions. The noise cancellation is impressive!",
    "rating": 5,
    "sentiment": "POSITIVE",
    "sentiment_score": 0.92,
    "is_active": true,
    "created": "2024-02-20T15:45:00Z",
    "updated": "2024-02-20T15:45:00Z",
    "reviewimage_set": [
      {
        "id": 1,
        "image": "https://cdn.example.com/reviews/headphones-review-1.jpg",
        "is_primary": true
      }
    ]
  },
  {
    "id": 16,
    "user": "jane_smith",
    "review_text": "Good product overall, but the battery life could be better. Works great for daily use.",
    "rating": 4,
    "sentiment": "POSITIVE",
    "sentiment_score": 0.65,
    "is_active": true,
    "created": "2024-02-18T10:30:00Z",
    "updated": "2024-02-18T10:30:00Z",
    "reviewimage_set": []
  }
]

​

Error Responses

{
  "detail": "Not found."
}

​

Create Product Review

POST /api/v1/products/{product_id}/reviews/

​

Authentication

Authorization: Bearer <your_jwt_token>

​

Path Parameters

​

Request Body

​

Request Example

curl -X POST "https://api.example.com/api/v1/products/1/reviews/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "review_text": "Amazing product! Exceeded my expectations.",
    "rating": 5
  }'

​

Response Example

{
  "success": "Review posted"
}

​

Error Responses

{
  "error": "You can't add a review for a product you didn't purchase."
}

{
  "rating": ["A valid integer is required."],
  "review_text": ["This field may not be blank."]
}

{
  "detail": "Authentication credentials were not provided."
}

{
  "detail": "Not found."
}

​

Get Specific Review

GET /api/v1/products/{product_id}/reviews/{review_id}/

​

Authentication

​

Path Parameters

​

Request Example

curl -X GET "https://api.example.com/api/v1/products/1/reviews/15/" \
  -H "Accept: application/json"

​

Response Example

{
  "id": 15,
  "user": "john_doe",
  "review_text": "Excellent sound quality and comfortable for long listening sessions.",
  "rating": 5,
  "sentiment": "POSITIVE",
  "sentiment_score": 0.92,
  "is_active": true,
  "created": "2024-02-20T15:45:00Z",
  "updated": "2024-02-20T15:45:00Z",
  "reviewimage_set": []
}

​

Error Responses

{
  "error": "Review doesn't exist"
}

​

Update Review

PUT /api/v1/products/{product_id}/reviews/{review_id}/

​

Authentication

Authorization: Bearer <your_jwt_token>

​

Path Parameters

​

Request Body

​

Request Example

curl -X PUT "https://api.example.com/api/v1/products/1/reviews/15/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "review_text": "Updated: Still an amazing product after 3 months of use!",
    "rating": 5
  }'

​

Response Example

{
  "id": 15,
  "user": "john_doe",
  "review_text": "Updated: Still an amazing product after 3 months of use!",
  "rating": 5,
  "sentiment": "POSITIVE",
  "sentiment_score": 0.92,
  "is_active": true,
  "created": "2024-02-20T15:45:00Z",
  "updated": "2024-03-03T09:30:00Z",
  "reviewimage_set": []
}

​

Error Responses

{
  "rating": ["Ensure this value is less than or equal to 5."]
}

{
  "detail": "Authentication credentials were not provided."
}

{
  "detail": "You do not have permission to perform this action."
}

{
  "error": "Review doesn't exist"
}

​

Delete Review

DELETE /api/v1/products/{product_id}/reviews/{review_id}/

​

Authentication

Authorization: Bearer <your_jwt_token>

​

Path Parameters

​

Request Example

curl -X DELETE "https://api.example.com/api/v1/products/1/reviews/15/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​

Response Example

(Empty response body)

​

Error Responses

{
  "detail": "Authentication credentials were not provided."
}

{
  "detail": "You do not have permission to perform this action."
}

{
  "error": "Review doesn't exist"
}

​

Review Rules and Validation

​

Rating Scale

1. Very Bad (1) - Extremely dissatisfied
2. Unsatisfied (2) - Below expectations
3. Just There (3) - Meets basic expectations
4. Satisfied (4) - Meets or slightly exceeds expectations
5. Very Satisfied (5) - Exceeds expectations significantly

​

Review Requirements

1. Purchase Verification: Users can only review products they have purchased
2. Authentication: Creating, updating, and deleting reviews requires authentication
3. Ownership: Users can only update or delete their own reviews
4. One Review Per User: Each user can only post one review per product (enforced at application level)

​

Automatic Features

1. Product Rating Update: Product’s average rating is automatically recalculated when reviews are added, updated, or deleted
2. Sentiment Analysis: Reviews may undergo automatic sentiment analysis to populate sentiment and sentiment_score fields
3. Timestamp Tracking: Creation and update timestamps are automatically maintained

​

Content Guidelines

• Review Text: Should be descriptive and provide useful information to other customers
• Minimum Length: While not enforced at API level, reviews should be substantive
• Prohibited Content: Reviews containing inappropriate content may be marked as inactive by administrators

​

Notes

• Reviews are sorted by creation date (most recent first) by default
• The is_active flag allows administrators to hide inappropriate reviews without deletion
• Sentiment analysis is performed automatically but may be null for older reviews
• Product ratings are calculated as the average of all active review ratings
• Review images are optional and managed separately from the review text
• Deleting a review permanently removes it from the database
• The product’s rating field is updated asynchronously after review operations