Advanced API Versioning
APIs change over time. New features get added, old approaches get replaced, and sometimes you need to fundamentally restructure things. API versioning lets you make these changes without breaking existing clients. The key is knowing when versioning is necessary and choosing the right strategy.
Versioning Strategies
URL versioning puts the version in the path:
GET /v1/users
GET /v2/users
This is the most visible and widely used approach. Clients clearly see which version they're using, and different versions can coexist easily.
Header versioning uses HTTP headers:
GET /users
Accept: application/vnd.myapi+json;version=2
This keeps URLs clean but hides version information. It's harder to test in browsers and less obvious when debugging.
Query parameter versioning adds version as a parameter:
GET /users?version=2
This is simple but feels awkward — version isn't really a filter on the data.
Recommendation: URL versioning is most practical for most APIs. It's explicit, easy to understand, and works everywhere.
When to Version
Not every change requires a new version. Understanding what breaks clients helps you version appropriately.
Breaking changes (require new version):
- Removing fields from responses
- Changing field types (string to number)
- Changing response structure
- Removing endpoints
- Changing authentication requirements
Non-breaking changes (no version needed):
- Adding new fields to responses
- Adding new endpoints
- Adding optional request parameters
- Bug fixes that don't change contracts
Deprecation Process
When retiring old versions, give clients time to migrate:
-
Announce deprecation: Update documentation and add deprecation headers to responses:
Deprecation: true Sunset: Sat, 1 Jun 2025 00:00:00 GMT -
Set end-of-life date: Give at least 6-12 months for major versions.
-
Monitor usage: Track which clients still use deprecated versions.
-
Communicate directly: Reach out to heavy users of deprecated versions.
-
Remove after transition: Only shut down when usage is minimal.
Version Maintenance
Supporting multiple versions has costs. Each version needs testing, documentation, and potentially bug fixes. Limit active versions — typically current and previous major version.
Consider feature flags for gradual rollouts instead of full versions when changes are smaller.