What are the main API versioning strategies, and how do you deprecate a version?

Question

IT Interview Practice · Accepted Answer

Versioning lets you evolve an API with **breaking changes** without breaking existing clients. There are three mainstream strategies, plus a deprecation process.

## The three strategies

**1. URI versioning** — the version is in the path.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Simplest and most visible; easy to route, cache, and test in a browser. Downside: it technically violates "the URI identifies a resource" (the same user now has two URLs). This is by far the most common choice (GitHub, Stripe historically).

**2. Custom header versioning** — the version travels in a header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Keeps URLs clean but is invisible in a browser and harder to cache.

**3. Media-type (content negotiation) versioning** — version in `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
The most "RESTful" (the resource URL is stable; only its representation is versioned), but the least approachable for consumers.

## What counts as breaking

```text
BREAKING      → remove/rename a field, change a type, change auth, tighten validation
NON-BREAKING  → add a new optional field, add a new endpoint, add an enum value*
```
Only breaking changes need a new version; add non-breaking changes to the current one.

## Deprecation process

1. **Announce** with dates in docs and changelog.
2. **Signal at runtime** with headers so clients notice programmatically:
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users/42>; rel="successor-version"
```
3. **Monitor** usage of the old version and reach out to remaining callers.
4. **Sunset** only after usage drops near zero.

## Why it matters

Interviewers ask this to see whether you can grow an API in production without breaking the clients that depend on it — a real operational concern, not a theoretical one. The strongest answers make two distinctions: first, that **most changes are non-breaking** and shouldn't trigger a version bump at all (additive changes go into the current version), reserving versioning for genuinely breaking changes; and second, that the *strategy* matters less than the *process* — a clear deprecation timeline with `Deprecation`/`Sunset` headers and usage monitoring is what actually protects consumers. URI versioning wins in practice for its visibility and tooling support, but knowing the trade-offs (header and media-type keep URLs stable and are more RESTful, at the cost of discoverability) shows you understand the design space rather than just cargo-culting `/v1/`.

The three strategies

What counts as breaking

Deprecation process

Why it matters

Related questions