Base URL & Versioning v1.2.0

Learn how to structure your API requests, handle versioning, and stay compatible with the BookEase platform.

Base URL

All API requests to BookEase should be made to the following base endpoint:

Endpoint

https://api.bookease.io

⚠️ Environment Note Use https://sandbox-api.bookease.io for testing and development. All other endpoints are for production traffic only.

API Versioning Strategy

BookEase uses URL-based versioning to ensure backward compatibility and smooth migrations. The current stable version is /v1/.

Request Format

Include the version prefix in all endpoint paths:

Pattern

GET https://api.bookease.io/v1/bookings/{id}
POST https://api.bookease.io/v1/services/{service_id}/schedule

Version Headers (Optional)

You may also specify a version using the Bookease-Version header. This is useful for granular patch-level updates:

Headers

Bookease-Version: 2024-11-15
Authorization: Bearer <your_api_key>

🔄 Header vs URL The URL prefix takes precedence. If both are provided, the URL version is used. The header is recommended for minor/patch updates within a major version.

Version Lifecycle

Each API version goes through a clear lifecycle to ensure predictable updates:

Status	Meaning	Action Required
Active	Fully supported, receiving new features and bug fixes	None
Maintenance	Security patches only. No new features.	Plan migration
Deprecated	Still functional but scheduled for removal	Migrate within 90 days
Sunset	Disabled. Requests return 410 Gone	Immediate migration required

Deprecation Headers

When a version enters maintenance or deprecation, responses will include:

Response Headers

Deprecation: true
Sunset: Sat, 01 Mar 2025 00:00:00 GMT
Link: ; rel="successor-version"

Code Examples

See how to properly format requests with the correct base URL and version across popular languages.

JavaScript (Fetch)

JavaScript

const response = await fetch('https://api.bookease.io/v1/bookings', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk_live_your_api_key',
    'Bookease-Version': '2024-11-15'
  },
  body: JSON.stringify({
    service_id: 'srv_8x7j9k',
    customer_email: 'user@example.com',
    start_time: '2024-12-15T10:00:00Z'
  })
});

const booking = await response.json();

Python (Requests)

Python

import requests

headers = {
    "Authorization": "Bearer sk_live_your_api_key",
    "Bookease-Version": "2024-11-15",
    "Content-Type": "application/json"
}

payload = {
    "service_id": "srv_8x7j9k",
    "customer_email": "user@example.com",
    "start_time": "2024-12-15T10:00:00Z"
}

response = requests.post(
    "https://api.bookease.io/v1/bookings",
    headers=headers,
    json=payload
)

booking = response.json()

cURL

Shell

curl -X POST https://api.bookease.io/v1/bookings \n  -H "Authorization: Bearer sk_live_your_api_key" \n  -H "Bookease-Version: 2024-11-15" \n  -H "Content-Type: application/json" \n  -d '{
    "service_id": "srv_8x7j9k",
    "customer_email": "user@example.com",
    "start_time": "2024-12-15T10:00:00Z"
  }'

Frequently Asked Questions

How long is a version supported?
Major versions are actively supported for a minimum of 24 months. Maintenance continues for an additional 6 months before sunset.

Can I mix versions in a single request?
No. All endpoints in a single request/response cycle must use the same major version. Webhooks will always use the version specified in your webhook endpoint configuration.

What happens when a version is sunset?
All requests to a sunset version will return a 410 Gone status with a JSON body containing migration guidance and successor version details.