How Do You Version an API at Scale?
Learn API versioning strategies, URI vs header versioning, and how to deprecate old versions safely at scale.
Expected Interview Answer
API versioning is the discipline of introducing breaking changes without disrupting existing clients, typically by embedding a version marker in the URL path, a request header, or the media type, and running old and new contracts side by side until callers migrate.
The most common approach is URI versioning (/v1/orders, /v2/orders) because it is explicit, cacheable, and easy to route at the gateway or load balancer, though it fragments the URL space. Header versioning (a custom header or Accept media-type parameter) keeps URLs clean and is favored for hypermedia-style APIs, but is harder to test with a browser and easy to forget. Whichever scheme is chosen, the deeper discipline is a deprecation policy: publish a sunset date, emit a Deprecation and Sunset header on old-version responses, monitor which clients still call the old version, and only retire it once usage drops to near zero. Backward-compatible changes (adding an optional field) should never require a new version at all — only removing, renaming, or changing the meaning of a field should trigger a version bump.
- Lets producers evolve a contract without breaking existing consumers overnight
- Gives operators a measurable, monitorable deprecation path instead of a hard cutover
- Keeps additive, backward-compatible changes cheap by reserving version bumps for real breaks
- Makes the blast radius of a breaking change explicit and opt-in for clients
AI Mentor Explanation
API versioning is like a cricket board publishing revised playing conditions for a new season while still honoring the old rulebook for matches already scheduled under it. Teams that registered under the v1 rules keep playing by them until the season ends, while new fixtures adopt v2 automatically. The board announces a cutoff date after which the old rulebook is retired, giving every team time to retrain umpires and players. That parallel support with a published sunset date is exactly how a versioned API keeps old clients working while new ones move forward.
Step-by-Step Explanation
Step 1
Classify the change
Decide if the change is backward-compatible (additive) or breaking (removed/renamed field, changed semantics) — only breaking changes need a new version.
Step 2
Choose a versioning scheme
Pick URI versioning, a custom header, or media-type versioning based on caching, routing and client-testing needs.
Step 3
Run versions in parallel
Deploy the new version alongside the old one behind the same gateway, routing by the version marker.
Step 4
Deprecate and sunset
Emit Deprecation/Sunset headers, monitor old-version traffic, and retire it only once usage is near zero.
What Interviewer Expects
- Distinguishes backward-compatible changes from breaking changes
- Names at least two versioning schemes (URI, header, media type) with a trade-off for each
- Describes a concrete deprecation process, not just “bump the version”
- Mentions monitoring old-version traffic before retiring it
Common Mistakes
- Bumping the version for every trivial additive change
- Choosing a scheme without discussing caching or routing implications
- Forgetting to define a deprecation and sunset timeline
- Never checking real traffic before decommissioning an old version
Best Answer (HR Friendly)
“API versioning means changing an API without breaking the apps that already depend on it. We usually mark the version in the URL or a header, keep the old version running alongside the new one, and give everyone a clear deadline and warning headers before we finally turn the old version off.”
Code Example
app.use("/v1/orders", (req, res, next) => {
res.set("Deprecation", "true")
res.set("Sunset", "Wed, 01 Oct 2026 00:00:00 GMT")
res.set("Link", '</v2/orders>; rel="successor-version"')
next()
}, ordersV1Router)
app.use("/v2/orders", ordersV2Router)
// Header-based alternative: same path, version negotiated via Accept
app.get("/orders", (req, res) => {
const accept = req.headers["accept"] || ""
if (accept.includes("application/vnd.acme.orders.v2+json")) {
return sendOrdersV2(req, res)
}
return sendOrdersV1(req, res)
})Follow-up Questions
- When is a field-level change backward-compatible versus breaking?
- How would you version a GraphQL API, which discourages traditional versioning?
- How do you measure which clients are still calling a deprecated version?
- What is the difference between URI versioning and content negotiation via the Accept header?
MCQ Practice
1. Which type of API change generally does NOT require a new version?
Additive, backward-compatible changes like a new optional field do not break existing clients, so they should not force a version bump.
2. What is the primary purpose of a Sunset header on a deprecated API version?
The Sunset header tells clients precisely when the deprecated version will be retired, giving them a deadline to migrate.
3. What is a common drawback of URI-based versioning (/v1/, /v2/)?
URI versioning is explicit and cacheable, but it duplicates route definitions and spreads a resource across multiple URL paths.
Flash Cards
What triggers an API version bump? — A breaking change — removing, renaming, or changing the meaning of a field, not an additive one.
Name two API versioning schemes. — URI versioning (/v1/resource) and header/media-type versioning (Accept or a custom header).
What does a Deprecation header signal? — That the current response comes from a version scheduled for retirement.
How do you decide when to retire an old version? — Monitor real traffic on it and retire only once usage drops to near zero, after the published sunset date.