How do you version a public REST API?
Interviewer Expectations for this Question
01
Core Competency
Assesses fundamental understanding of REST API Design conventions, runtime behavior, and memory/performance considerations.
02
Evaluation Criteria
Hiring managers look for precision, avoidance of ambiguous jargon, and ability to explain trade-offs under real production conditions.
Comprehensive Model Answer
Verified Solution
Common strategies:
- URI path versioning:
https://api.example.com/v1/orders. Most visible and easiest to route and cache, at the cost of polluting the URL. - Query parameter:
/orders?version=2. Easy but easy to forget and awkward to cache. - Custom media type:
Accept: application/vnd.example.v2+json. Purest REST approach but harder to test and document. - Custom header:
X-Api-Version: 2. Clean URLs, but invisible and frequently missed.
For a public API, URI versioning is the pragmatic default. More important than the mechanism is the policy: prefer additive, backward-compatible changes; never change the meaning of an existing field; announce deprecations early with Deprecation and Sunset headers; keep old versions running for a defined window; and protect consumers with contract tests in CI.
Candidate Response Strategy & Interview Tips
- Start with a concise one-sentence summary: Deliver a direct, confident answer first before expanding into nuances.
- Demonstrate real-world trade-offs: Discuss where this approach excels and when you would avoid it in production systems.
- Discuss complexity & edge cases: Proactively explain time/space complexity or boundary conditions (null values, scale limits).
- Prepare for interviewer follow-ups: Technical hiring panels frequently probe deeper into concurrency, backward compatibility, or alternative libraries.