API Versioning
2 min read
Pick a versioning strategy before your first breaking change forces one — three options, one easy answer.
Pick a versioning strategy before your first breaking change forces one — three options, one easy answer.
How It Works
API versioning is how you make breaking changes without breaking existing clients. Three strategies: URL path (/v1/users, /v2/users) — explicit, easy to route, clients must update URLs; request header (Accept: application/vnd.myapp.v2+json) — clean URLs but harder to test and debug; query parameter (?version=2) — simple but visually ugly. Versioning granularity: whole-API (all endpoints share a version) vs per-endpoint (endpoints version independently). Whole-API is simpler; per-endpoint allows gradual migration but creates matrix complexity. In interviews, defaulting to URL path versioning is almost always safe and shows you plan for change.
Real-World Example
GitHub initially used header-based versioning (
Accept: application/vnd.github.v3+json) for their REST API, which worked for SDK consumers but made ad-hoc cURL debugging harder. They later moved toward URL-based versioning for new endpoints. Meanwhile, their GraphQL API eliminates versioning entirely by additive schema evolution — clients request only the fields they know about, and new fields are added without breaking old queries. The lesson: pick your versioning strategy when you design v1, because retrofitting is painful. Most teams converge on URL-path versioning for REST because it's the easiest to communicate.
Test Yourself
Scenario: You run a public API at api.example.com/users that returns { id, email, name }. Product wants to split name into firstName and lastName — a breaking change for existing clients. How do you roll this out without breaking consumers?
Get notified when we launch
One email when the full practice product is live. No spam.