API Versioning

PhantomJSON uses URI versioning for all API endpoints.

Current Version

The current API version is v1. All endpoints are prefixed with /v1:

curl https://api.phantomjson.app/v1/users
curl https://api.phantomjson.app/v1/products
curl https://api.phantomjson.app/v1/flights

How Versioning Works

Each API version is a complete, independent API. When you call /v1/users, you’re calling version 1 of the Users endpoint.

URI Format

https://api.phantomjson.app/v{version}/{resource}

Examples:

# v1 endpoints
GET /v1/users
GET /v1/products
GET /v1/flights

# Future v2 endpoints (when released)
GET /v2/users
GET /v2/products

Version Behavior

Behavior	Description
Stable URLs	Once released, v1 URLs will never change
Independent versions	v1 and v2 coexist without affecting each other
No header negotiation	Version is always in the URL, never in headers
No query parameters	Version is not passed as ?version=1

Why URI Versioning?

URI versioning is chosen for PhantomJSON because:

• Visible in URLs — Version is immediately apparent in browser, logs, and documentation
• Easy to document — Clear which version an endpoint belongs to
• Cache-friendly — Different versions have different URLs
• Developer-friendly — No need to set headers or query params
• CDN-compatible — Each version gets its own cache key

What Happens When a New Version is Released?

When breaking changes are introduced:

1. v1 continues to work — Existing integrations are not affected
2. v2 is released — New features and breaking changes are available
3. Both versions coexist — You can migrate at your own pace
4. v1 is eventually deprecated — With advance notice and migration guide

Breaking Changes

A new version is only created for breaking changes such as:

• Removing or renaming endpoints
• Changing response schemas
• Modifying authentication requirements
• Changing pagination behavior

Non-Breaking Changes

These changes do not require a new version:

• Adding new endpoints
• Adding new optional query parameters
• Adding new fields to responses
• Adding new response status codes

Migration Guide

When a new version is released, a migration guide will be provided:

/v2/users  → What changed from v1
/v2/users  → How to update your integration
/v2/users  → Timeline for v1 deprecation

Versioning Best Practices

1. Always use the version prefix — Include /v1 in all API requests
2. Check documentation — New features may be version-specific
3. Pin your version — Don’t use /v1 casually; pin to specific versions in production
4. Monitor changelog — Stay informed about upcoming changes
5. Migrate when ready — When a new version is released, migrate at your own pace