Skip to main content

​
Welcome to Trippins API

The Trippins API is a REST-based service that powers the hotel booking platform. It provides programmatic access to manage users, houses, reservations, reviews, and all core booking operations.

​
Base URL and Versioning

All API requests are made to the following base URL: 
https://localhost:8443
The API uses URL path versioning. All endpoints are prefixed with /v1/api: 
https://localhost:8443/v1/api/{resource}

​
Example Endpoints

  • https://localhost:8443/v1/api/houses - List all houses
  • https://localhost:8443/v1/api/users - Manage users
  • https://localhost:8443/v1/api/reservations - Handle reservations

​
API Architecture

The Trippins API follows RESTful principles with resource-based URLs and standard HTTP methods:
MethodDescription
GETRetrieve resources
POSTCreate new resources
PUTUpdate existing resources
DELETERemove resources

​
Resource Categories

The API is organized into the following resource groups:

User Management

Create, read, update, and delete user accounts

Housing Management

Manage hotel listings, tags, and properties

Reservation Management

Handle booking operations and availability

Review Management

Manage customer reviews and ratings

Authentication

JWT-based authentication and authorization

Advanced Search

Query houses by tags and star ratings

​
Response Format

All API responses return JSON-formatted data with consistent structure.

​
Success Response

Successful requests return the appropriate HTTP status code and JSON payload: 
{
  "code": 1,
  "name": "Beachfront Villa",
  "location": "Malibu, CA",
  "price": 350,
  "stars": 5,
  "description": "Luxurious villa with ocean views",
  "acepted": true,
  "tags": [
    {"id": "beach"},
    {"id": "wifi"}
  ]
}

​
Common HTTP Status Codes

​
200 OK
success
The request succeeded. Response includes the requested data.
​
201 Created
success
A new resource was successfully created.
​
204 No Content
success
The request succeeded but there’s no content to return (typically for DELETE operations).
​
400 Bad Request
error
The request was malformed or contains invalid parameters.
​
401 Unauthorized
error
Authentication is required or credentials are invalid.
​
403 Forbidden
error
The authenticated user doesn’t have permission to access this resource.
​
404 Not Found
error
The requested resource doesn’t exist.
​
500 Internal Server Error
error
An unexpected error occurred on the server.

​
Error Handling

When an error occurs, the API returns a structured error response:

​
Error Response Format

{
  "error": "Unauthorized",
  "message": "Bad credentials"
}

​
Error Response with Problem Details

For some endpoints, detailed error information follows RFC 7807 Problem Details: 
{
  "type": "https://localhost:8443/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "Invalid input provided",
  "instance": "/v1/api/users"
}
​
type
string
A URI reference identifying the problem type
​
title
string
A short, human-readable summary of the problem
​
status
integer
The HTTP status code
​
detail
string
A detailed explanation of the problem
​
instance
string
The URI reference of the specific occurrence

​
Authentication Overview

Most API endpoints require authentication using JWT (JSON Web Tokens). See the Authentication page for complete details on:
  • Logging in to obtain a JWT token
  • Including the token in API requests
  • Token expiration and renewal
  • Role-based access control

​
Quick Authentication Example

# 1. Login to get JWT token
curl -X POST https://localhost:8443/v1/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "password123"
  }'

# 2. Use token in subsequent requests
curl https://localhost:8443/v1/api/houses \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Rate Limiting

Currently, the Trippins API does not implement rate limiting. However, clients should implement reasonable request throttling to avoid overloading the server.
Best practices:
  • Avoid making excessive concurrent requests
  • Implement exponential backoff for retries
  • Cache responses when appropriate

​
Pagination

Certain endpoints support pagination for large result sets:

​
Pagination Parameters

​
page
integer
default:"0"
Zero-based page number
​
size
integer
default:"6"
Number of items per page

​
Pagination Example

GET /v1/api/rooms/extra?page=0&size=6

​
Pagination Response

{
  "content": [...],
  "totalPages": 10,
  "totalElements": 58,
  "size": 6,
  "number": 0,
  "first": true,
  "last": false,
  "numberOfElements": 6,
  "empty": false
}
​
content
array
The array of items for the current page
​
totalPages
integer
Total number of pages available
​
totalElements
integer
Total number of items across all pages
​
number
integer
Current page number (zero-based)
​
first
boolean
Whether this is the first page
​
last
boolean
Whether this is the last page

​
Content Types

The API accepts and returns JSON data. Always include the appropriate headers: 
Content-Type: application/json
Accept: application/json

​
Image Endpoints

Housing image endpoints work with binary image data: 
# Upload image
Content-Type: application/json

# Retrieve image
Accept: image/jpeg

​
Getting Started

To begin using the Trippins API:
  1. Authenticate: Obtain a JWT token via the /v1/api/login endpoint
  2. Include Token: Add the token to the Authorization header of all requests
  3. Make Requests: Use standard HTTP methods to interact with resources
  4. Handle Responses: Process JSON responses and handle errors appropriately

Next: Authentication

Learn how to authenticate with JWT tokens

Build docs developers (and LLMs) love

Get started for freeTalk to us