Designing an API Versioning Strategy

API versioning allows you to evolve your API without breaking existing clients.

Why Versioning?

Without versioning:
Change response field → All clients break immediately

With versioning:
Change v2 response → v1 clients unaffected

Versioning Strategies

URI Versioning

GET /v1/users/123
GET /v2/users/123

Pros: Clear, cacheable, easy to test in browser Cons: URI "pollution", not RESTful purists

Header Versioning

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

Pros: Clean URIs Cons: Harder to test, not cacheable by CDN

Query Parameter

GET /users/123?api_version=2

Pros: Easy to test Cons: Easy to forget, clutters URLs

Backward Compatibility Rules

SAFE changes (non-breaking):
  + Adding new fields
  + Adding new optional parameters
  + Adding new endpoints
  + Relaxing validation rules

BREAKING changes (require new version):
  - Removing fields
  - Renaming fields
  - Changing field types
  - Making optional params required

Versioning in Practice

Route requests:
GET /v1/orders → OrdersController_v1
GET /v2/orders → OrdersController_v2

Shared business logic:
both controllers use OrderService (same)
different: serialization/response format

Deprecation Strategy

1. Announce deprecation (Sunset header)
2. 6-month deprecation window
3. Send emails to API key owners using old version
4. Return deprecation warnings in responses
5. Sunset date: stop supporting v1

Sunset: Sat, 31 Dec 2026 23:59:59 GMT

API Changelog

Maintain public changelog:

v2.1.0 (2026-03-01):
  + Added pagination to /orders
  + Added filter by status

v2.0.0 (2026-01-01):
  BREAKING: Renamed user.fullName → user.name

Conclusion

URI versioning is the industry standard for simplicity. Use semantic versioning, document breaking changes explicitly, and give clients 6+ months for migration.