Skip to main content

​
Overview

The Reservation Management API provides endpoints for creating, reading, updating, and deleting reservations. Reservations link users (clients) to housing listings with specific check-in and check-out dates.
All endpoints require JWT authentication via the Authorization: Bearer {token} header.

​
Get All Reservations

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

​
Response

​
reservations
array
Array of ReservationDTO objects
[
  {
    "id": 1,
    "checkIn": "2024-06-15T14:00:00",
    "checkOut": "2024-06-20T11:00:00",
    "valorated": true,
    "clientDni": "11223344C",
    "housingCode": 1,
    "housingName": "Hotel Mediterranean"
  },
  {
    "id": 2,
    "checkIn": "2024-07-01T15:00:00",
    "checkOut": "2024-07-05T10:00:00",
    "valorated": false,
    "clientDni": "99887766B",
    "housingCode": 2,
    "housingName": "City Center Apartments"
  }
]

​
Status Codes

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

​
Get Reservation by ID

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

​
Response

Returns a single ReservationDTO object with all reservation details. 
{
  "id": 1,
  "checkIn": "2024-06-15T14:00:00",
  "checkOut": "2024-06-20T11:00:00",
  "valorated": true,
  "clientDni": "11223344C",
  "housingCode": 1,
  "housingName": "Hotel Mediterranean"
}

​
Status Codes

CodeDescription
200Successfully retrieved reservation
404Reservation not found
403Forbidden - Access denied

​
Create Reservation

Create a new reservation with the provided details. 
curl -X POST https://localhost:8443/v1/api/reservations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "checkIn": "2024-08-10T15:00:00",
    "checkOut": "2024-08-15T11:00:00",
    "valorated": false,
    "clientDni": "11223344C",
    "housingCode": 1,
    "housingName": "Hotel Mediterranean"
  }'

​
Request Body

​
checkIn
string
required
Check-in date and time in ISO 8601 format (e.g., “2024-08-10T15:00:00” or “2024-08-10”)
​
checkOut
string
required
Check-out date and time in ISO 8601 format (e.g., “2024-08-15T11:00:00” or “2024-08-15”)
​
valorated
boolean
Whether the reservation has been rated (default: false for new reservations)
​
clientDni
string
required
DNI of the client making the reservation (must be an existing user)
​
housingCode
integer
required
Code/ID of the housing to reserve (must be an existing housing listing)
​
housingName
string
required
Name of the housing (should match the housingCode)

​
Response

Returns the created reservation with an auto-generated ID. 
{
  "id": 3,
  "checkIn": "2024-08-10T15:00:00",
  "checkOut": "2024-08-15T11:00:00",
  "valorated": false,
  "clientDni": "11223344C",
  "housingCode": 1,
  "housingName": "Hotel Mediterranean"
}

​
Status Codes

CodeDescription
201Reservation created successfully
400Invalid input (e.g., invalid dates, non-existent client or housing)
403Forbidden - Access denied

​
Update Reservation

Update an existing reservation.
​
id
integer
required
ID of the reservation to update (e.g., 1)
curl -X PUT https://localhost:8443/v1/api/reservations/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "checkIn": "2024-08-12T14:00:00",
    "checkOut": "2024-08-17T12:00:00",
    "valorated": false,
    "clientDni": "11223344C",
    "housingCode": 1,
    "housingName": "Hotel Mediterranean"
  }'

​
Request Body

All ReservationDTO fields can be updated (see Create Reservation for field descriptions).
Changing clientDni or housingCode will reassign the reservation to a different client or housing.

​
Response

Returns the updated reservation. 
{
  "id": 1,
  "checkIn": "2024-08-12T14:00:00",
  "checkOut": "2024-08-17T12:00:00",
  "valorated": false,
  "clientDni": "11223344C",
  "housingCode": 1,
  "housingName": "Hotel Mediterranean"
}

​
Status Codes

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

​
Delete Reservation

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

​
Response

No content is returned on successful deletion.

​
Status Codes

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

​
Admin Reservation Management

Administrators have additional endpoints for managing reservations:

​
Accept Reservation

Requires ADMIN role. Marks a reservation as accepted by setting the valorated field to true.
curl -X PUT https://localhost:8443/v1/api/admin/reservations/decision/1 \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN"
Status Codes:
  • 200 - Reservation accepted successfully
  • 404 - Reservation not found
  • 403 - Forbidden (requires ADMIN role)
  • 401 - Unauthorized (invalid JWT)

​
Deny Reservation

Requires ADMIN role. Denies and deletes a reservation from the system.
curl -X DELETE https://localhost:8443/v1/api/admin/reservations/decision/1 \
  -H "Authorization: Bearer ADMIN_JWT_TOKEN"
Status Codes:
  • 204 - Reservation denied and removed successfully
  • 404 - Reservation not found
  • 403 - Forbidden (requires ADMIN role)
  • 401 - Unauthorized (invalid JWT)

​
Date Handling

The API uses SQL Date format internally but accepts ISO 8601 datetime strings. Dates can be provided in the following formats:
  • YYYY-MM-DD (e.g., “2024-08-10”)
  • YYYY-MM-DDTHH:mm:ss (e.g., “2024-08-10T15:00:00”)
Always ensure checkOut date is after checkIn date to avoid validation errors.

​
Authentication

All Reservation Management endpoints require JWT authentication: 
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Admin-specific endpoints require a JWT token with the ROLE_ADMIN role.

​
Error Responses

​
error
string
Error type
​
message
string
Detailed error message
{
  "error": "Bad Request",
  "message": "Check-out date must be after check-in date"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us