Skip to main content

​
Overview

The Review Management API provides endpoints for creating, reading, updating, and deleting reviews. Reviews allow users to rate and comment on their experiences at housing listings.
All endpoints require JWT authentication via the Authorization: Bearer {token} header.

​
Get All Reviews

Retrieve a list of all reviews in the system. 
curl -X GET https://localhost:8443/v1/api/reviews \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Response

​
reviews
array
Array of ReviewDTO objects
[
  {
    "reviewId": 1,
    "rating": 5,
    "comment": "Excellent hotel with amazing views! The staff was very friendly and helpful.",
    "hotelCode": 1,
    "userName": "John Doe",
    "userDni": "11223344C"
  },
  {
    "reviewId": 2,
    "rating": 4,
    "comment": "Great location in the city center. Clean and comfortable rooms.",
    "hotelCode": 2,
    "userName": "Jane Smith",
    "userDni": "99887766B"
  }
]

​
Status Codes

CodeDescription
200Successfully retrieved list of reviews
403Forbidden - Access denied

​
Get Review by ID

Retrieve a specific review by its ID.
​
id
integer
required
ID of the review to retrieve (e.g., 1)
curl -X GET https://localhost:8443/v1/api/reviews/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Response

Returns a single ReviewDTO object with all review details. 
{
  "reviewId": 1,
  "rating": 5,
  "comment": "Excellent hotel with amazing views! The staff was very friendly and helpful.",
  "hotelCode": 1,
  "userName": "John Doe",
  "userDni": "11223344C"
}

​
Status Codes

CodeDescription
200Successfully retrieved review
404Review not found
403Forbidden - Access denied

​
Create Review

Create a new review with the provided details. 
curl -X POST https://localhost:8443/v1/api/reviews \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 5,
    "comment": "Wonderful experience! Highly recommended.",
    "hotelCode": 1,
    "userName": "John Doe",
    "userDni": "11223344C"
  }'

​
Request Body

​
rating
integer
required
Numeric rating (typically 1-5, where 5 is the highest rating)
​
comment
string
required
Text review/comment describing the user’s experience
​
hotelCode
integer
required
Code/ID of the housing/hotel being reviewed (must be an existing housing listing)
​
userName
string
required
Name of the user writing the review
​
userDni
string
required
DNI of the user writing the review (must be an existing user)
The reviewId field is auto-generated and should not be included in the request body.

​
Response

Returns the created review with an auto-generated reviewId. 
{
  "reviewId": 3,
  "rating": 5,
  "comment": "Wonderful experience! Highly recommended.",
  "hotelCode": 1,
  "userName": "John Doe",
  "userDni": "11223344C"
}

​
Status Codes

CodeDescription
201Review created successfully
400Invalid input (e.g., invalid rating, non-existent hotel or user)
403Forbidden - Access denied

​
Update Review

Update an existing review.
​
id
integer
required
ID of the review to update (e.g., 1)
curl -X PUT https://localhost:8443/v1/api/reviews/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 4,
    "comment": "Updated review: Still a great place, but the breakfast could be improved.",
    "hotelCode": 1,
    "userName": "John Doe",
    "userDni": "11223344C"
  }'

​
Request Body

All ReviewDTO fields can be updated (see Create Review for field descriptions).
Users should only be able to update their own reviews. Ensure proper authorization checks are in place.

​
Response

Returns the updated review. 
{
  "reviewId": 1,
  "rating": 4,
  "comment": "Updated review: Still a great place, but the breakfast could be improved.",
  "hotelCode": 1,
  "userName": "John Doe",
  "userDni": "11223344C"
}

​
Status Codes

CodeDescription
200Review updated successfully
404Review not found
400Invalid input
403Forbidden - Access denied

​
Delete Review

Delete a review by its ID.
​
id
integer
required
ID of the review to delete (e.g., 1)
curl -X DELETE https://localhost:8443/v1/api/reviews/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Response

No content is returned on successful deletion.
Users should only be able to delete their own reviews. Administrators may delete any review.

​
Status Codes

CodeDescription
204Review deleted successfully
404Review not found
403Forbidden - Access denied

​
Get Comments for a House (Paginated)

Retrieve paginated comments/reviews for a specific house.
This endpoint is part of the Custom AJAX API and provides pagination support for displaying reviews on the frontend.
​
id
integer
required
ID of the house
​
page
integer
Page number (0-based, default: 0)
​
size
integer
Number of items per page (default: 3)
curl -X GET "https://localhost:8443/v1/api/rooms/1/comments/extra?page=0&size=6" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Response

Returns a paginated list of Review entities (full objects including hotel and user details). 
{
  "content": [
    {
      "reviewId": 1,
      "rating": 5,
      "comment": "Excellent hotel with amazing views!",
      "hotel": {
        "code": 1,
        "name": "Hotel Mediterranean",
        "location": "Barcelona, Spain"
      },
      "user": {
        "dni": "11223344C",
        "name": "John Doe",
        "email": "[email protected]"
      }
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 6,
    "offset": 0
  },
  "totalPages": 2,
  "totalElements": 10,
  "last": false,
  "first": true
}

​
Status Codes

CodeDescription
200Successfully retrieved paginated comments
500Internal server error

​
Rating Guidelines

5 Stars

Exceptional - Exceeded expectations in every way

4 Stars

Great - Minor issues but overall very positive experience

3 Stars

Good - Met expectations with some room for improvement

2 Stars

Fair - Below expectations with notable issues

1 Star

Poor - Major problems and disappointing experience

​
Best Practices

For Users:
  • Leave reviews only after completing your stay
  • Be honest and constructive in your feedback
  • Include specific details about your experience
  • Rate fairly based on the housing category and price point
For Developers:
  • Validate that users can only review properties they’ve reserved
  • Implement rate limiting to prevent review spam
  • Consider requiring reservations to be marked as valorated: true before allowing reviews
  • Sanitize user input in comments to prevent XSS attacks

​
Authentication

All Review Management endpoints require JWT authentication: 
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

​
Error Responses

​
error
string
Error type
​
message
string
Detailed error message
{
  "error": "Bad Request",
  "message": "Rating must be between 1 and 5"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us