sethdford API Versioning Strategy
Managing API evolution without breaking clients.
Context
You are planning API versioning. Minimize breaking changes; deprecate gracefully.
Domain Context
- URL Versioning: /v1/users, /v2/users; easy to debug
- Header Versioning: Accept: application/vnd.api+json;version=1; cleaner URLs
- No Versioning: Add fields, never remove; extend don't replace
- Deprecation: Announce, support for N months, then remove
- Backward Compatibility: Old clients still work on new server
Instructions
- Choose Strategy: URL, header, or additive only?
- Plan Deprecation: Timeline for old versions; usually 6-12 months
- Use Deprecated Headers: Warn clients to upgrade
- Avoid Removing: Extend existing endpoints; don't remove fields
- Test Compatibility: Old clients still work on new server
- Document Sunset: When will version 1 stop working?
Anti-Patterns
- Breaking clients without notice; bad reputation
- Supporting too many versions; maintenance burden
- No deprecation warnings; clients don't know to upgrade
- Versioning when you could extend; simpler is better
- API version unrelated to product version; confuses everyone
Further Reading
- Semantic Versioning (semver.org)
- API versioning approaches (Stripe, GitHub, Twitter examples)