Reviews API

Endpoints for creating and managing book reviews. All endpoints require authentication.

Create or Update Review

Create a new review or update an existing review for a book.

POST /reviews

Authentication

Required (Bearer token)

Rate Limits

• Free tier: 50 reviews per month
• Premium tier: Unlimited
• Bookstore tier: Unlimited

Request Body

{
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "rating": 5,
  "content": "An absolute masterpiece of modern literature. Salinger's portrayal of teenage angst and alienation is timeless and profoundly moving."
}

Rating Scale

• 1 - Poor
• 2 - Fair
• 3 - Good
• 4 - Very Good
• 5 - Excellent

Response

{
  "id": "dd0e8400-e29b-41d4-a716-446655440008",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "johndoe",
    "displayName": "John Doe",
    "avatarUrl": "https://cdn.bookwish.app/avatars/johndoe.jpg",
    "tier": "premium"
  },
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "book": {
    "id": "bb0e8400-e29b-41d4-a716-446655440006",
    "isbn": "9780316769174",
    "title": "The Catcher in the Rye",
    "authors": ["J.D. Salinger"],
    "coverUrl": "https://covers.bookwish.app/9780316769174.jpg"
  },
  "rating": 5,
  "content": "An absolute masterpiece of modern literature. Salinger's portrayal of teenage angst and alienation is timeless and profoundly moving.",
  "likeCount": 0,
  "isLiked": false,
  "createdAt": "2024-03-21T16:00:00Z",
  "updatedAt": "2024-03-21T16:00:00Z"
}

Errors

• 400 ValidationError - Invalid request body (missing rating, invalid rating value)
• 401 Unauthorized - Not authenticated
• 403 Forbidden - Monthly review limit reached (free tier)
• 404 NotFound - Book not found
• 429 TooManyRequests - Rate limit exceeded
• 500 InternalServerError - Server error

Example

curl -X POST "https://api.bookwish.app/reviews" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
    "rating": 5,
    "content": "An absolute masterpiece of modern literature."
  }'

Get Review

Get a specific review by ID.

GET /reviews/:id

Authentication

Required (Bearer token)

Path Parameters

• id - Review ID

Response

{
  "id": "dd0e8400-e29b-41d4-a716-446655440008",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "johndoe",
    "displayName": "John Doe",
    "avatarUrl": "https://cdn.bookwish.app/avatars/johndoe.jpg",
    "tier": "premium"
  },
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "book": {
    "id": "bb0e8400-e29b-41d4-a716-446655440006",
    "isbn": "9780316769174",
    "title": "The Catcher in the Rye",
    "authors": ["J.D. Salinger"],
    "coverUrl": "https://covers.bookwish.app/9780316769174.jpg"
  },
  "rating": 5,
  "content": "An absolute masterpiece of modern literature. Salinger's portrayal of teenage angst and alienation is timeless and profoundly moving.",
  "likeCount": 15,
  "isLiked": true,
  "createdAt": "2024-03-18T11:00:00Z",
  "updatedAt": "2024-03-18T11:00:00Z"
}

Errors

• 401 Unauthorized - Not authenticated
• 404 NotFound - Review not found
• 500 InternalServerError - Server error

Example

curl "https://api.bookwish.app/reviews/dd0e8400-e29b-41d4-a716-446655440008" \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Review

Update an existing review.

PUT /reviews/:id

Authentication

Required (Bearer token - review author only)

Path Parameters

• id - Review ID

Request Body

{
  "rating": 4,
  "content": "Updated: While still excellent, I've reconsidered some aspects upon reflection. The narrative style is brilliant but occasionally repetitive."
}

Response

{
  "id": "dd0e8400-e29b-41d4-a716-446655440008",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "bookId": "bb0e8400-e29b-41d4-a716-446655440006",
  "rating": 4,
  "content": "Updated: While still excellent, I've reconsidered some aspects upon reflection. The narrative style is brilliant but occasionally repetitive.",
  "likeCount": 15,
  "isLiked": true,
  "createdAt": "2024-03-18T11:00:00Z",
  "updatedAt": "2024-03-21T17:00:00Z"
}

Errors

• 400 ValidationError - Invalid request body
• 401 Unauthorized - Not authenticated
• 403 Forbidden - Not the review author
• 404 NotFound - Review not found
• 429 TooManyRequests - Rate limit exceeded
• 500 InternalServerError - Server error

Example

curl -X PUT "https://api.bookwish.app/reviews/dd0e8400-e29b-41d4-a716-446655440008" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 4,
    "content": "Updated: While still excellent, I have reconsidered some aspects."
  }'

Delete Review

Delete a review.

DELETE /reviews/:id

Authentication

Required (Bearer token - review author only)

Path Parameters

• id - Review ID

Response

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

Errors

• 401 Unauthorized - Not authenticated
• 403 Forbidden - Not the review author
• 404 NotFound - Review not found
• 500 InternalServerError - Server error

Example

curl -X DELETE "https://api.bookwish.app/reviews/dd0e8400-e29b-41d4-a716-446655440008" \
  -H "Authorization: Bearer YOUR_TOKEN"

Like Review

Like a review.

POST /reviews/:id/like

Authentication

Required (Bearer token)

Path Parameters

• id - Review ID

Response

{
  "success": true,
  "likeCount": 16,
  "isLiked": true
}

Errors

• 400 ValidationError - Already liked
• 401 Unauthorized - Not authenticated
• 404 NotFound - Review not found
• 429 TooManyRequests - Rate limit exceeded
• 500 InternalServerError - Server error

Example

curl -X POST "https://api.bookwish.app/reviews/dd0e8400-e29b-41d4-a716-446655440008/like" \
  -H "Authorization: Bearer YOUR_TOKEN"

Unlike Review

Remove like from a review.

DELETE /reviews/:id/like

Authentication

Required (Bearer token)

Path Parameters

• id - Review ID

Response

{
  "success": true,
  "likeCount": 15,
  "isLiked": false
}

Errors

• 400 ValidationError - Not liked
• 401 Unauthorized - Not authenticated
• 404 NotFound - Review not found
• 500 InternalServerError - Server error

Example

curl -X DELETE "https://api.bookwish.app/reviews/dd0e8400-e29b-41d4-a716-446655440008/like" \
  -H "Authorization: Bearer YOUR_TOKEN"

Review Guidelines

When writing reviews, please follow these guidelines:

1. Be Honest: Share your genuine thoughts and opinions
2. Be Respectful: Avoid personal attacks on authors or other reviewers
3. Be Specific: Explain what you liked or didn't like
4. Avoid Spoilers: Use spoiler warnings if discussing plot details
5. Stay On Topic: Keep reviews focused on the book

Review Moderation

Reviews are subject to moderation and may be removed if they:

• Contain hate speech or harassment
• Include spam or promotional content
• Violate copyright with excessive quotations
• Contain personal information
• Are off-topic or not related to the book

Review Object Fields

Field	Type	Description
id	string	Unique review identifier
userId	string	Author's user ID
user	object	Author's user details
bookId	string	Book ID
book	object	Book details
rating	number	Star rating (1-5)
content	string	Review content text
likeCount	number	Number of likes
isLiked	boolean	Whether current user liked this review
createdAt	string	Creation timestamp (ISO 8601)
updatedAt	string	Last update timestamp (ISO 8601)

Rating Statistics

When fetching reviews for a book (via /books/:id/reviews), the response includes aggregate rating statistics:

{
  "items": [...],
  "averageRating": 4.5,
  "totalReviews": 1248,
  "ratingDistribution": {
    "5": 782,
    "4": 312,
    "3": 98,
    "2": 34,
    "1": 22
  }
}

Rating Distribution Fields

Field	Type	Description
averageRating	number	Average rating across all reviews (0-5)
totalReviews	number	Total number of reviews
ratingDistribution	object	Count of reviews by rating (1-5)