What is API Versioning?
Learn what API versioning is, common strategies like URL and header versioning, and how to manage breaking changes safely.
Expected Interview Answer
API versioning is the practice of labeling breaking changes to an API with a distinct version identifier — in the URL, a header, or a query parameter — so existing clients keep working against the version they were built for while new clients can opt into newer behavior.
As APIs evolve, some changes are additive and safe (new optional fields, new endpoints), while others are breaking (removed fields, changed response shapes, renamed endpoints). Versioning gives breaking changes a home: clients pin to /v1/ or send an Accept-Version header, and the server keeps serving that contract until the version is formally deprecated and sunset. Common strategies include URL path versioning (/v1/users), header versioning (Accept: application/vnd.api+json;version=2), and query parameter versioning, each trading off discoverability, cacheability, and routing simplicity differently. Good versioning also comes with a deprecation policy and clear migration documentation so clients are not broken without warning.
- Lets the API evolve without breaking existing integrations
- Gives clients a predictable migration window
- Enables gradual rollout and A/B comparison of new contracts
- Improves API discoverability and long-term maintainability
AI Mentor Explanation
API versioning is like different editions of the official laws of cricket — the 2000 code and the 2017 code — where a match can be explicitly played under one edition so both umpires and players know exactly which rules apply. A club that has not updated its scorers can keep running the older edition safely while newer clubs adopt the latest rules. That explicit, coexisting rule-edition labeling is exactly what versioning gives an API.
Step-by-Step Explanation
Step 1
Choose a versioning strategy
Pick URL path (/v1/), header, or query parameter versioning based on your discoverability and caching needs.
Step 2
Introduce a new version for breaking changes
Bump the version only when a change would break existing clients, not for additive fields.
Step 3
Run versions in parallel
Serve both old and new versions simultaneously so clients migrate on their own schedule.
Step 4
Deprecate and sunset
Publish a deprecation timeline, notify clients, and remove the old version after the migration window closes.
What Interviewer Expects
- Clear distinction between breaking and non-breaking (additive) changes
- Familiarity with URL, header, and query-param versioning trade-offs
- Mention of a deprecation and sunset policy, not just launching new versions
- Awareness that versioning adds maintenance cost of running multiple contracts
Common Mistakes
- Bumping the version for every minor, non-breaking change
- Never deprecating old versions, leading to unbounded maintenance burden
- Choosing a versioning strategy without considering caching implications
- Failing to document migration steps for clients moving between versions
Best Answer (HR Friendly)
“API versioning means labeling changes to an API so it does not break apps that are already using it. When I make a change that would break existing clients, I release it as a new version, like /v2/, and keep the old version running until everyone has had a chance to migrate.”
Code Example
const express = require("express");
const app = express();
app.get("/v1/users/:id", (req, res) => {
res.json({ id: req.params.id, name: "Legacy shape" });
});
app.get("/v2/users/:id", (req, res) => {
res.json({ id: req.params.id, fullName: "New shape", email: "user@example.com" });
});Follow-up Questions
- What is the difference between a breaking and a non-breaking API change?
- How would you design a deprecation policy for an old API version?
- What are the trade-offs between URL path and header-based versioning?
- How does API versioning interact with caching and CDN behavior?
MCQ Practice
1. Which of these is a breaking API change?
Removing a field that clients rely on breaks their existing parsing logic, requiring a version bump.
2. What is a common URL-based versioning pattern?
Path-based versioning like /v1/users is widely used for its simplicity and cache-friendliness.
3. Why is a deprecation policy important in API versioning?
A deprecation policy communicates timelines so clients can migrate without being broken unexpectedly.
Flash Cards
What is API versioning? — Labeling breaking API changes with a version identifier so existing clients keep working.
Name three common versioning strategies. — URL path versioning, header versioning, and query parameter versioning.
What counts as a breaking change? — Removing fields, renaming endpoints, or changing response shapes clients depend on.
Why is a sunset policy needed? — To give clients a clear, bounded window to migrate before an old version is removed.