Versioning Strategies

There are several approaches to API versioning, each with trade-offs. Let's explore the most common strategies.

1. URL Path Versioning

Include the version in the URL path.

GET /api/v1/users
GET /api/v2/users

Pros

• Highly visible and explicit
• Easy to test different versions
• Simple to implement in routing
• Cache-friendly (different URLs)

Cons

• Changes the resource URI
• Need to update all client URLs
• Can lead to code duplication

Implementation

app.get('/api/v1/users', handleV1Users);
app.get('/api/v2/users', handleV2Users);

2. Query Parameter Versioning

Pass version as a query parameter.

GET /api/users?version=1
GET /api/users?v=2

Pros

• Resource URI stays the same
• Easy to add to requests
• Optional (can default to latest)

Cons

• Can be overlooked
• Mixed with other parameters
• Less visible in documentation

3. Header Versioning

Use a custom header to specify version.

GET /api/users
X-API-Version: 2

Or with Accept header:

GET /api/users
Accept: application/vnd.myapi.v2+json

Pros

• Clean URIs
• Proper HTTP semantics
• Supports content negotiation

Cons

• Hidden from URL
• Harder to test in browser
• Requires header configuration

4. Content Negotiation (Media Type)

Version through content type.

GET /api/users
Accept: application/vnd.company.api+json; version=2

Pros

• RESTful approach
• Semantic versioning
• Flexible format support

Cons

• Complex to implement
• Hard to discover versions
• Documentation challenges

Comparison

Strategy	Visibility	RESTful	Caching	Ease of Use
URL Path	High	Low	Good	High
Query Param	Medium	Low	Tricky	High
Header	Low	Medium	Good	Medium
Media Type	Low	High	Good	Low

Exercise: Version Router

Recommendations

For Public APIs

Use URL path versioning (/v1/)

• Most discoverable
• Easiest for developers
• Best documentation support

For Internal APIs

Use header versioning

• Cleaner URIs
• More flexible
• Proper HTTP semantics

Version Numbering

v1, v2, v3          # Major versions only
v1.0, v1.1, v2.0    # Major.minor
2024-01-15          # Date-based (rare)

Best Practices

1. Start with v1 - Even your first API
2. Support 2-3 versions - Not indefinitely
3. Communicate deprecation - Give clients time
4. Provide migration guides - Help clients upgrade
5. Use sunset headers - Indicate deprecation dates

Sunset: Sat, 01 Jan 2025 00:00:00 GMT
Deprecation: true

Summary

Choose...	When...
URL Path	Public API, need visibility
Query Param	Simple addition to existing API
Header	Internal API, clean URIs
Media Type	Strict REST adherence