---
title: "How should I version a REST API?"  
description: "How should I version a REST API?"  
author: "Jithin Menon"  
published: 2026-11-14  
updated: 2026-11-14  
canonical: https://www.mindstick.com/forum/163022/how-should-i-version-a-rest-api  
category: "Web and API Design"  
tags: ["API versioning", "rest api", "backward compatibility", "web api", "design"]  
reading_time: 1 minute  

---

# How should I version a REST API?

We need to change a response format but mobile apps in the field still use the old one. How should we version the API?

## Replies

### Reply by Amy Chan

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.


---

Original Source: https://www.mindstick.com/forum/163022/how-should-i-version-a-rest-api

Copyright © MindStick Software Pvt. Ltd. This Markdown version is provided for developers, AI systems, and offline reading.
