REST API Versioning — URI vs Header vs Media Type
Fast recall
Quick revision
Core answer
Understanding that versioning involves trade-offs, not a single correct answer
Saying 'just add v1 to everything' without explaining why and the deprecation strategy
Mention the real-world choices (Stripe = URI, GitHub = Accept header) and semver vs date-based versioning
Interview-ready guide
Interview answer
API versioning is how you evolve your API without breaking existing clients. The choice of strategy affects discoverability, REST compliance, and operational complexity.
Three strategies
- URI versioning (
/api/v1/orders,/api/v2/orders): most common, discoverable, easy to route in API gateways and load balancers; Stripe's model - Header versioning (
API-Version: 2or custom header): keeps URIs stable; requires custom routing logic; harder to test without tooling - Accept/Content-Type versioning (
Accept: application/vnd.company.v2+json): fully REST-compliant; version is a content negotiation concern; GitHub uses this; complex to implement and consume
Deprecation — the part most teams get wrong
- Announce the sunset date in the
Sunset: Sat, 01 Jan 2027 00:00:00 GMTresponse header on every response from the deprecated version - Monitor traffic — never remove a version while clients are still calling it; check logs or API gateway metrics
- Provide a concrete migration guide: what changed, what the new endpoint looks like, how to migrate field by field
In Spring MVC
- Path prefix versioning is the cleanest:
@RequestMapping("/v1")on a separate controller class per version - Copy-paste versioned controllers is an anti-pattern — prefer a shared service layer and version only the request/response DTOs that changed
REST API Versioning — URI vs Header vs Media Type
Direct Answer
URI versioning (/v1/users) is the most pragmatic — visible, cacheable, easy to test. Header versioning (X-API-Version: 2) keeps URLs clean but breaks caching. Media type versioning is REST-pure but complex to implement and test.
Common Mistakes & Pitfalls
Saying 'just add v1 to everything' without explaining why and the deprecation strategy
Check your understanding
Answer these without looking back at the article.
- How do you handle backwards compatibility when adding new fields to an API response?
- What is the Sunset header and how do you use it for deprecation?
- How do you version internal APIs used only by your own microservices?
Related interview prep categories
1Want a guided curriculum order?
These modules are also sequenced in our flagship backend interview track — open it when you prefer an ordered path instead of browsing by topic.