How do you handle versioning in a REST API?
Learn how to version a REST API with URI path, query, header and media-type strategies, their trade-offs, deprecation tips and interview questions.
Expected Interview Answer
You version a REST API so you can introduce breaking changes without disrupting existing clients, most commonly via URI path versioning (/v1/orders), query parameters (?version=1), custom headers, or content negotiation using the Accept header (media-type versioning).
Each strategy trades off visibility and purity. URI versioning is the most explicit and cache-friendly but pollutes URLs. Header and media-type versioning keep URLs clean and are considered more RESTful but are harder to test and discover. Good practice is to version only on breaking changes, keep additive changes backward compatible, document a deprecation policy, and support old versions for a defined window before sunsetting them.
- Lets the API evolve without breaking existing clients
- Gives clients time to migrate on their own schedule
- Makes breaking changes explicit and predictable
- Supports clear deprecation and sunset policies
- Enables parallel support of multiple client versions
AI Mentor Explanation
Think of updated playing conditions rolled out as named editions, so a series can run under the 2023 rules while a legacy tournament finishes under the 2019 rules without confusion. Umpires know exactly which edition applies to each match. API versioning does the same, letting new clients use v2 rules while older clients keep working under v1 until they migrate.
Step-by-Step Explanation
Step 1
Decide what counts as breaking
Version only on breaking changes; keep additive changes like new optional fields backward compatible within the same version.
Step 2
Pick a strategy
Choose URI path (/v1), query parameter (?version=1), custom header, or Accept media-type versioning based on your needs.
Step 3
Apply it consistently
Use the same versioning scheme across all endpoints so clients have one predictable rule to follow.
Step 4
Document and communicate
Publish the current version, changelog and a deprecation policy so clients know what changed and by when to migrate.
Step 5
Deprecate and sunset
Support old versions for a defined window, warn via headers or docs, then retire them on a clear timeline.
What Interviewer Expects
- Naming multiple versioning strategies
- Explaining URI vs header vs media-type trade-offs
- Distinguishing breaking from additive changes
- Mentioning a deprecation and sunset policy
- Awareness that URI versioning is cache-friendly
Common Mistakes
- Versioning on every change, including non-breaking ones
- Mixing multiple versioning schemes across endpoints
- Ignoring backward compatibility for additive changes
- Having no deprecation or sunset policy
- Assuming there is only one correct versioning approach
Best Answer (HR Friendly)
“API versioning is a way to update a service without breaking the apps that already use it, usually by labelling the address as v1 or v2 or by asking for a version in the request. It lets old apps keep working while new ones get the latest features, and gives everyone time to switch.”
Code Example
# 1. URI path versioning
GET /v1/orders/1042
GET /v2/orders/1042
# 2. Query parameter
GET /orders/1042?version=2
# 3. Custom header
GET /orders/1042
X-API-Version: 2
# 4. Media-type (content negotiation)
GET /orders/1042
Accept: application/vnd.myapp.v2+jsonFollow-up Questions
- What is the difference between URI and header-based versioning?
- Why is media-type versioning considered more RESTful?
- How do you deprecate an old API version gracefully?
- What changes count as breaking versus non-breaking?
- How does versioning interact with HTTP caching?
MCQ Practice
1. Which versioning strategy is the most cache-friendly and explicit?
URI path versioning (/v1/orders) makes the version part of the URL, so it is explicit and works naturally with HTTP caches.
2. Which change should trigger a new API version?
Only breaking changes warrant a new version; additive, backward-compatible changes can stay within the current version.
3. Which header is used for media-type (content negotiation) versioning?
Media-type versioning uses the Accept header, e.g. application/vnd.myapp.v2+json, to request a specific version.
Flash Cards
Why version a REST API? — To make breaking changes without disrupting existing clients.
Name four versioning strategies. — URI path, query parameter, custom header, and Accept media-type versioning.
When should you create a new version? — Only on breaking changes; keep additive changes backward compatible.
Which strategy is most cache-friendly? — URI path versioning, since the version is part of the URL.