An API with external consumers you don't control is effectively a permanent contract — you can't force every client to update the moment you want to change something, and API versioning is the mechanism that lets your API evolve without breaking clients still relying on the old behavior.
API versioning is the practice of managing changes to an API's contract over time while maintaining compatibility for existing clients. Common strategies include URL versioning (/v1/users), header-based versioning (Accept: application/vnd.api+json;version=2), and query parameter versioning — each with different tradeoffs around cacheability, discoverability, and client migration friction.
Why API Versioning Matters (and When to Skip It)
Once external clients depend on your API's shape, changing that shape without warning breaks them — versioning gives you a controlled way to introduce breaking changes (new required fields, removed fields, changed response shapes) while giving existing clients time to migrate on their own schedule, rather than forcing an immediate coordinated update.
Skip formal versioning for fully internal APIs where you control both sides (client and server deploy together, or the API has no external consumers) — in that case, you can often make changes directly without the overhead of maintaining multiple concurrent versions.
Getting Started with API Versioning
URL-based versioning, the most common and discoverable approach:
GET /v1/users/123
GET /v2/users/123
Header-based versioning, keeping URLs stable while the version lives in a header:
GET /users/123
Accept: application/vnd.myapi+json;version=2
Core API Versioning Concepts Every Developer Should Know
Not every change requires a new version — only breaking changes do. Adding a new optional field, adding a new endpoint, or relaxing a validation rule are backward-compatible changes clients can safely ignore. Removing a field, changing a field's type, or changing existing behavior are breaking changes that need a version bump (or careful, deliberate migration handling).
URL versioning is the most discoverable and cache-friendly, since the version is visible in the URL itself and different versions are trivially different cache keys — but it means the resource "identity" technically changes between versions, which some API design philosophies consider architecturally impure compared to header-based approaches.
Header-based versioning keeps URLs stable (arguably more RESTful, since a resource's URL doesn't change based on API version), but is less discoverable (you can't just look at a URL to know the version) and requires more careful cache configuration since the same URL can return different response shapes based on a header.
Deprecation needs an explicit timeline and communication, not silent removal. Clients on an old version need advance notice and a migration path — a Sunset header, deprecation warnings in responses, and direct communication to known API consumers are all part of responsibly retiring an old version, not just a technical versioning scheme decision.
Sunset: Sat, 01 Aug 2026 00:00:00 GMT
Deprecation: true
Common API Versioning Mistakes and How to Fix Them
Mistake 1: bumping the version for every small change, including backward-compatible ones, fragmenting your API into far more versions than necessary and increasing maintenance burden. Fix: version only for genuinely breaking changes, and add backward-compatible changes without a version bump.
Mistake 2: maintaining old versions indefinitely without a deprecation plan, accumulating unbounded technical debt as more versions pile up over time. Fix: set an explicit deprecation timeline for each version at the time a new version ships, and communicate it proactively.
Mistake 3: not documenting what changed between versions clearly enough for clients to migrate confidently. Fix: maintain a clear changelog per version with concrete migration guidance, not just a version number bump with no explanation.
When Should You Use URL Versioning Instead of Header-Based Versioning?
Use URL versioning when discoverability and simplicity matter most — it's immediately visible, easy to test manually, and works well with standard HTTP caching without extra configuration. Use header-based versioning when you want cleaner, more RESTful-purist URLs and are willing to accept the added complexity of content negotiation and careful cache configuration for the tradeoff.
API Versioning in Production
Set and communicate an explicit deprecation timeline whenever a new API version ships, rather than letting old versions accumulate indefinitely without a retirement plan. Also version deliberately — only for genuinely breaking changes — to avoid fragmenting your API into more versions than the actual rate of breaking change justifies.
If your API currently makes breaking changes without a versioning strategy and just hopes clients update in time, that's a real operational risk worth addressing before it causes an unplanned outage for a consumer you don't control.