api-versioning

API Versioning

Strategies for versioning APIs, managing breaking changes, and deprecating old versions gracefully.

When to Use This Skill

• Choosing an API versioning strategy
• Planning for breaking changes
• Deprecating API versions
• Managing multiple API versions
• Designing for API evolution

Why Version APIs?

APIs are contracts with clients.
Breaking changes break clients.

Without versioning:
- Change field name → All clients break
- Remove endpoint → All clients break
- Change behavior → Unexpected client behavior

With versioning:
- Old clients use old version
- New clients use new version
- Gradual migration possible

Versioning Strategies

URL Path Versioning

https://api.example.com/v1/users
https://api.example.com/v2/users

Pros:
- Clear and explicit
- Easy to understand
- Easy to route
- Easy to cache

Cons:
- Version embedded in client code
- Multiple URLs for same resource
- Not truly RESTful (URL should identify resource)

Header Versioning

GET /users
Accept: application/vnd.example.v1+json

or custom header:
GET /users
API-Version: 1

Pros:
- Clean URLs
- More RESTful
- Version separate from resource

Cons:
- Hidden from URL
- Harder to test in browser
- Requires header support

Query Parameter Versioning

GET /users?version=1
GET /users?api-version=2023-01-01

Pros:
- Easy to add
- Optional (can default)
- Easy to test

Cons:
- Can be forgotten
- Pollutes query string
- Caching complexity

Content Negotiation

Accept: application/vnd.example+json; version=1

Pros:
- Standard HTTP mechanism
- Flexible

Cons:
- Complex to implement
- Hard to discover

Strategy Comparison

Versioning Schemes

Integer Versions

v1, v2, v3

Pros: Simple, clear major changes
Cons: Coarse-grained

Best for: Public APIs with infrequent breaking changes

Semantic Versioning

v1.2.3 (major.minor.patch)

Major: Breaking changes
Minor: New features (backward compatible)
Patch: Bug fixes

Pros: Fine-grained, predictable
Cons: More complex

Best for: Libraries, SDKs

Date-Based Versioning

2023-01-15, 2023-06-01

Pros: Clear when version was current
Cons: Doesn't indicate change magnitude

Best for: Frequently changing APIs (Stripe, GitHub)

Example (Stripe):
Stripe-Version: 2023-10-16

What Requires a New Version?

Breaking Changes (New Major Version)

Always breaking:
- Removing endpoint
- Removing field
- Changing field type
- Changing field meaning
- Renaming field
- Adding required field
- Changing authentication
- Changing error format

Non-Breaking Changes (No Version Needed)

Safe changes:
- Adding new endpoint
- Adding optional field
- Adding new enum value
- Adding optional parameter
- Relaxing validation
- Adding new error codes

Version Management

Running Multiple Versions

Option 1: Separate codebases
/v1/* → v1 service
/v2/* → v2 service

Pros: Full isolation
Cons: Duplication, maintenance burden

Option 2: Shared codebase with branching
if (version == 1) {
  return formatV1(data);
} else {
  return formatV2(data);
}

Pros: Single codebase
Cons: Code complexity grows

Option 3: Transformation layer
Internal model → Version-specific transformer → Response

Pros: Clean separation
Cons: Requires transformation code

Version Routing

API Gateway pattern:

Client → Gateway → Route by version → Service

Gateway responsibilities:
- Parse version from URL/header
- Route to appropriate backend
- Transform if needed
- Handle defaults

Deprecation Strategy

Lifecycle Phases

1. Current: Active development
2. Maintained: Bug fixes only
3. Deprecated: No changes, sunset announced
4. Sunset: Removed

Timeline example:
v1: Current (12 months)
v1: Maintained when v2 launches (6 months)
v1: Deprecated (6 months)
v1: Sunset

Deprecation Communication

Headers:
Deprecation: true
Sunset: Sat, 1 Jul 2024 00:00:00 GMT
Link: <https://api.example.com/v2/docs>; rel="successor-version"

Response body:
{
  "data": {...},
  "_deprecation": {
    "message": "This API version is deprecated",
    "sunset": "2024-07-01",
    "successor": "https://api.example.com/v2"
  }
}

Migration Support

Provide:
1. Migration guide documenting all changes
2. Mapping of old → new endpoints
3. Code examples for common operations
4. SDK updates with compatibility layer
5. Sandbox environment for testing

Best Practices

Default Version

Options:
1. Require explicit version (recommended for public APIs)
2. Default to latest (dangerous for stability)
3. Default to oldest supported (conservative)

Recommendation: Require version, fail without it

Version in Response

Include version info in responses:

{
  "data": {...},
  "_meta": {
    "api_version": "v2",
    "deprecated": false
  }
}

Graceful Degradation

When version unknown:
1. Return error with supported versions
2. Redirect to documentation
3. Return latest version with warning

HTTP 400 Bad Request
{
  "error": "Unknown API version",
  "supported_versions": ["v1", "v2"],
  "documentation": "https://docs.example.com/api"
}

Testing Multiple Versions

Test matrix:
- All supported versions
- Breaking change boundaries
- Deprecation warnings
- Sunset behavior

Automated tests:
- Contract tests per version
- Backward compatibility tests
- Migration path tests

Real-World Examples

Stripe

Date-based: 2023-10-16
Header: Stripe-Version
Default: Account's API version
Rollback: Can pin to older version
Upgrades: Preview in dashboard

GitHub

Date-based: 2022-11-28
Header: X-GitHub-Api-Version
Default: Latest
Preview features: Accept header

Google

URL path: /v1/, /v2/
Discovery document for each version
Long deprecation cycles (years)

Twilio

Date-based: 2010-04-01
URL path includes date
Very long support windows

Anti-Patterns

1. Too many versions
   → Consolidate, set deprecation schedule

2. Breaking changes in minor versions
   → Follow semantic versioning strictly

3. No deprecation warnings
   → Always communicate before breaking

4. Instant sunset
   → Give clients time to migrate (6-12 months minimum)

5. Version per endpoint
   → Keep all endpoints in sync per version

Related Skills

• api-design-fundamentals - API design patterns
• idempotency-patterns - Safe API operations
• quality-attributes-taxonomy - Maintainability attributes