The best approach is to avoid breaking changes: add new fields, do not remove or rename old ones, and keep old behaviour working. Version only when a breaking change is unavoidable.
Common ways to version:
In the URL: /api/v2/orders. It is the most visible, easy to test and easy to route. Many teams use it.
In a header: Api-Version: 2 or a custom media type. The URL stays clean, but it is harder to try in a browser.
In a query string: ?api-version=2. Easy, though a bit untidy.
Tips:
Keep old versions alive for a set period and tell clients the end date.
Log which version is used, so you know when it is safe to retire one.
In ASP.NET Core, the Asp.Versioning libraries support all three styles.
Mobile apps are the hardest, because users do not update at once. Plan to support old versions for months.
Markdown for AI
A clean, structured version of this page for AI assistants and LLMs.
We use cookies to ensure you have the best browsing experience on our website. By using our site, you
acknowledge that you have read and understood our
Cookie Policy &
Privacy Policy.
The best approach is to avoid breaking changes: add new fields, do not remove or rename old ones, and keep old behaviour working. Version only when a breaking change is unavoidable.
Common ways to version:
/api/v2/orders. It is the most visible, easy to test and easy to route. Many teams use it.Api-Version: 2or a custom media type. The URL stays clean, but it is harder to try in a browser.?api-version=2. Easy, though a bit untidy.Tips:
Mobile apps are the hardest, because users do not update at once. Plan to support old versions for months.