API Versioning Strategies
APIs are contracts. Clients depend on the structure of responses. Change an endpoint and you break clients. Versioning is how you evolve APIs without breaking existing clients.
Why Versioning Matters
Your API has clients—users' applications, third parties, your own front-end. These clients expect stability. If you rename a field or change a response structure, they break.
Versioning lets you make breaking changes without immediately breaking all clients. Old versions continue to work. Clients migrate to new versions on their own schedule.
URL Versioning
Include version in the URL: /api/v1/users, /api/v2/users. Most visible, easiest to understand. Clients explicitly choose the version. Most APIs use this.
Downside: you maintain multiple versions. /api/v1 and /api/v2 might both need to work for years. This duplicates code and testing.
Header Versioning
Specify version in a header: Accept: application/vnd.myapp.v2+json. Cleaner URLs but harder to test in a browser. Less common.
Query Parameter Versioning
/api/users?version=2. Easy but messy. Endpoint URLs become inconsistent.
Breaking vs Non-Breaking Changes
Non-breaking: adding a new field to a response. Clients expecting the old structure still work; they just ignore the new field.
Breaking: removing a field, renaming a field, changing a field's type, reordering array elements in meaningful ways. Clients expecting the old structure break.
Make non-breaking changes to existing versions. Only break clients when you bump to a new version.
Deprecation Policies
You can't maintain old versions forever. Plan for sunset. A deprecation policy tells clients when old versions stop working.
For public APIs: announce deprecation at least 6-12 months before sunset. Internal APIs can deprecate faster. Partner APIs should follow contractual agreements.
Send deprecation warnings in responses. Include headers indicating the version will be sunset on a date. Use 410 Gone status when a version is no longer available.
Internal vs External APIs
Internal APIs used only by your own front-end don't strictly need versioning. You control both ends. Update front-end and back-end together. No breaking changes are actually broken if everything deploys simultaneously.
External or partner APIs need versioning. You don't control the clients. They can't update on your schedule.
Semantic Versioning Applied to APIs
v1.0.0: MAJOR.MINOR.PATCH. Increment MAJOR for breaking changes. Increment MINOR for non-breaking changes. Increment PATCH for bug fixes.
In URLs, usually only MAJOR is included: /api/v1, /api/v2. MINOR and PATCH are implicit—all v1.x versions are compatible.
The Reality for Most Applications
For internal APIs, versioning is optional if you control both front-end and back-end. Deploy both together, no versioning needed.
For partner APIs or public APIs, versioning is required. A client depends on your API. Breaking changes are unacceptable without a long deprecation period.
Maintaining Multiple Versions
The cost of multiple versions: duplicated code, duplicated tests, duplicated bug fixes. A security vulnerability found in v1 might affect v2. You need to patch both.
Keep old versions alive only as long as necessary. Communicate sunset dates clearly. Push clients to migrate. Once v1 sunset date arrives, stop supporting it.
Starting with Versioning
Even if you don't think you'll need it, start with /api/v1. The first version should be v1, not v0. This gives you room to deprecate later without awkwardness.