API Versioning
Evolving an API without breaking existing clients — the discipline that decides whether you can change your API or are held hostage by it.
What is API versioning?
API versioning is how you change an API’s behavior without breaking the clients already depending on it. Once external consumers — mobile apps you can’t force-update, partner integrations, third-party developers — depend on your API’s shape, any incompatible change breaks them. Versioning is the contract-management strategy that lets the API evolve anyway: introduce v2 while v1 keeps working, migrate consumers deliberately, retire v1 on a schedule.
The strategies and their tradeoffs
URL path versioning (/v1/users, /v2/users) is the most common — explicit, cache-friendly, trivially visible in logs and docs; critics call it un-RESTful (the resource didn’t change, its representation did). Header versioning (Accept: application/vnd.api.v2+json) keeps URLs clean and is arguably more correct, but it’s invisible in a browser, harder to test, and easier to get wrong. Query parameter (?version=2) is simple but muddies caching. There’s no universal winner — path versioning’s discoverability wins for most public APIs; the deeper point is picking one and applying it consistently. The more sophisticated stance many teams reach: version sparingly, and prefer additive, non-breaking evolution (add fields, never remove or repurpose them; make new fields optional) so most changes need no version bump at all — GraphQL leans hard into this with field deprecation over versioned endpoints.
The part everyone underestimates: deprecation
Creating v2 is easy; retiring v1 is the hard, neglected discipline. Without a deprecation process — communicated timelines, usage monitoring to know who’s still on v1, Sunset headers, and enforced end-of-life — you accumulate versions forever, each one maintenance burden and attack surface. The teams that version well are the ones that sunset well: they can actually remove old versions because they tracked usage and gave notice, rather than supporting v1 through v7 simultaneously out of fear.
What people get wrong
- Versioning for changes that could be additive — a new optional field rarely needs a whole new version.
- No deprecation strategy — versions accumulate indefinitely because nothing is ever retired.
- Breaking changes within a version: silently repurposing a field or tightening validation breaks clients even without a version bump.
Primary source: Microsoft REST API Guidelines — versioning
Historical figures and technical concepts for informational purposes only. Not technical, professional, legal, or financial advice. Sources: Official Documentation.