What are the main API versioning strategies in REST and what are their tradeoffs?
Answer
Three main versioning approaches exist. URL path versioning (/v1/users) is the most common and explicit — version is visible in the URL, easy to route and test, but "pollutes" the URL structure and requires clients to update base URLs. Header versioning (API-Version: 2 or Accept: application/vnd.myapi.v2+json) keeps URLs clean and is semantically correct (the URL identifies the resource, not the version), but it is harder to test in a browser and less visible. Query parameter versioning (/users?version=2) is easy to add but is non-standard and can interfere with caching. URL path versioning is recommended for most public APIs due to visibility and simplicity. Never change a published version — create a new one and run old and new in parallel until clients migrate.
Previous
What is HATEOAS and how is it implemented?
Next
What are the pagination strategies in REST APIs?
More REST API Design Questions
View all →- Intermediate What is HATEOAS and how is it implemented?
- Intermediate What are the pagination strategies in REST APIs?
- Intermediate What is rate limiting and how is it communicated in REST APIs?
- Intermediate How does HTTP caching work in REST APIs with ETag and Cache-Control?
- Intermediate What are the OAuth 2.0 grant types and when do you use each?