Pattern: API versioning strategies

Need to evolve an API without breaking existing clients. Different versioning approaches have different trade-offs.

Three main API versioning strategies:

1. URL path versioning (most common):

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

Pros: Very explicit, easy to understand
Cons: Lots of route duplication
Used by: Twitter, Stripe, GitHub

1. Header versioning:

Accept: application/vnd.api+json; version=2
X-API-Version: 2

Pros: Clean URLs, no route duplication
Cons: Less visible, harder to test in browser
Used by: GitHub (also supports URL)

1. Query parameter:

/api/users?version=2

Pros: Easy to add, works in browser
Cons: Can be cached incorrectly, less clean

Best practices regardless of strategy:

• Additive changes don't need new version (add fields, never remove)
• Deprecation policy: announce, give migration period, sunset
• Version the API, not individual endpoints
• Support at most 2-3 versions simultaneously
• Provide migration guides between versions
• Default to latest stable version for new clients
• Include version in response headers for debugging

Recommendation: URL versioning for public APIs (most discoverable),
header versioning for internal APIs (cleaner).

Breaking changes are inevitable. A versioning strategy lets you evolve the API while giving clients time to migrate.