API Overview

Introduction

The Gustaffo Reservations Application exposes a RESTful API for interacting with the system. The API is secured using OAuth2 and requires appropriate authentication and authorization.

API Documentation

The API is documented using OpenAPI/Swagger, which provides a comprehensive and interactive interface for exploring the available endpoints.

Access the API documentation at: /swagger-ui.html

Authentication

The API uses OAuth2 for authentication. Clients must obtain an access token before making requests to protected endpoints.

Authentication Flow

1. Client obtains an access token using credentials or authorization code flow
2. Client includes the token in the Authorization header of subsequent requests
3. The server validates the token and authorizes the request based on the user's roles

API Structure

The API is organized into the following main areas:

Room Availability

• Base Path: /sse
• Key Endpoints:
  • POST /sse/availableRoomTypes: Initiate a room availability search
  • GET /sse/availableRoomTypes/{processId}: Subscribe to real-time search results

Reservations

• Base Path: /api/reservations
• Key Endpoints:
  • POST /api/reservations: Create a new reservation
  • GET /api/reservations/{id}: Get reservation details
  • PUT /api/reservations/{id}: Update a reservation
  • DELETE /api/reservations/{id}: Cancel a reservation

Hotels

• Base Path: /api/hotels
• Key Endpoints:
  • GET /api/hotels: List all hotels
  • GET /api/hotels/{id}: Get hotel details

User Management

• Base Path: /api/users
• Key Endpoints:
  • POST /api/users: Create a new user
  • GET /api/users/me: Get current user profile

Response Format

API responses are typically in JSON format and follow a consistent structure:

{
  "data": { /* Response data */ },
  "meta": { /* Metadata about the response */ },
  "errors": [ /* Array of errors, if any */ ]
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of requests. Error responses include detailed information about the error and how to resolve it.

{
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "message": "Invalid input data",
      "details": {
        "field": "email",
        "issue": "must be a valid email address"
      }
    }
  ]
}

Pagination

Endpoints that return collections of resources support pagination using the following query parameters:

• page: Page number (0-based)
• size: Number of items per page
• sort: Sorting criteria (format: property,direction)

Example: GET /api/hotels?page=0&size=10&sort=name,asc