Skip to main content

​
Introduction

The Reservations API is a RESTful API built with Go that provides a comprehensive booking and merchant management system. The API supports user authentication, merchant operations, booking management, and customer interactions.

​
Base URL

All API requests should be made to: 
http://localhost:{PORT}/api/v1
The port is configured via the PORT environment variable. In production, this would be your domain: 
https://api.yourdomain.com/api/v1

​
Request Format

The API accepts JSON-encoded request bodies. Always include the Content-Type header: 
Content-Type: application/json

​
Example Request

curl -X POST https://api.yourdomain.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

​
Response Format

All successful responses return data wrapped in a data object:

​
Success Response

​
data
object
The response payload containing the requested data
{
  "data": {
    // Response data here
  }
}

​
Error Response

Error responses include an error object with a descriptive message:
​
error
object
​
message
string
A human-readable error message describing what went wrong
{
  "error": {
    "message": "Invalid credentials provided"
  }
}

​
HTTP Status Codes

The API uses standard HTTP status codes to indicate success or failure:
Status CodeDescription
200OK - Request succeeded
201Created - Resource successfully created
400Bad Request - Invalid request parameters
401Unauthorized - Invalid or missing authentication
404Not Found - Resource doesn’t exist
500Internal Server Error - Something went wrong on the server

​
Common Error Scenarios

​
Validation Errors

When request validation fails, you’ll receive a 400 status with details: 
{
  "error": {
    "message": "email is required"
  }
}

​
Authentication Errors

Missing or invalid authentication returns 401: 
{
  "error": {
    "message": "authentication required"
  }
}

​
Rate Limiting

Currently, the API does not enforce rate limiting. However, we recommend implementing client-side throttling to avoid overwhelming the server.

​
API Versioning

The API is currently at version 1 (/api/v1). All endpoints are prefixed with this version identifier. Breaking changes will be introduced in new versions while maintaining backward compatibility for existing versions.

​
Environments

The API behavior can be configured using the APP_ENV environment variable:
  • development - Development environment with debug logging
  • production - Production environment with optimized settings

​
Core Resources

The API provides access to the following core resources:
  • Authentication - User login, signup, and OAuth flows
  • Bookings - Create, retrieve, and manage bookings
  • Merchants - Merchant profiles, settings, and dashboard
  • Customers - Customer management and history
  • Services - Service catalog and categories
  • Team - Team member management
  • Locations - Business location management
  • Products - Product catalog
Each resource has dedicated endpoints documented in the API Reference section.

Build docs developers (and LLMs) love

Get started for freeTalk to us