When building Web APIs, one inevitable challenge is **change**. As your application grows, you’ll add new features, change contracts, or even remove old functionality. But what happens to existing clients who still depend on the old API?
That’s where **API versioning** comes in. It allows you to evolve your API safely without breaking existing consumers.
🔑 Why Do We Need API Versioning?
* **Backward compatibility** – Old clients continue to work.
* **Gradual migration** – Clients can upgrade at their own pace.
* **Flexibility** – You can experiment with new versions.
* **Safe deprecation** – Retire old versions without sudden breaks.
📌 API Versioning Strategies
1. **URI Path Versioning (Most Common)**
https://api.example.com/v1/customers
https://api.example.com/v2/customers
✅ Easy to use and document
❌ URL changes for every version
2. **Query String Versioning**
https://api.example.com/customers?api-version=1.0
✅ Very simple to implement
❌ Not as RESTful (query strings are usually for filters)
3. **Header Versioning**
GET /customers
Header: api-version: 1.0
✅ Keeps URLs clean
❌ Requires client to manage headers
4. **Content Negotiation (Media Type)**
Accept: application/json; version=1.0
✅ Standards-friendly
❌ More complex to manage
⚙️ Implementing Versioning in ASP.NET Core
Microsoft provides a handy NuGet package for API versioning:
powershell
Install-Package Microsoft.AspNetCore.Mvc.Versioning
Step 1: Configure Services
csharp
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true; // Adds headers like api-supported-versions
options.ApiVersionReader = new UrlSegmentApiVersionReader();
// Options: QueryStringApiVersionReader("api-version")
// HeaderApiVersionReader("x-api-version")
});
}
Step 2: Create Versioned Controllers
`csharp
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/customers")]
[ApiController]
public class CustomersV1Controller : ControllerBase
{
[HttpGet]
public IActionResult Get() => Ok("Customer list from V1");
}
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/customers")]
[ApiController]
public class CustomersV2Controller : ControllerBase
{
[HttpGet]
public IActionResult Get() => Ok("Customer list from V2 with new fields");
}
Step 3: Testing Requests
* `GET /api/v1/customers` → handled by **V1 controller**
* `GET /api/v2/customers` → handled by **V2 controller**
## 🔧 Best Practices for API Versioning
1. Use **URI path versioning** for public APIs (clear & user-friendly).
2. Use **Header or Media Type versioning** for internal APIs (cleaner approach).
3. Always **document versions** using Swagger (OpenAPI).
4. Define a **deprecation strategy** – mark old versions and set timelines for removal.
✅ Conclusion
API versioning is essential for **scalable, maintainable, and client-friendly** Web APIs. In ASP.NET Core, you can easily implement versioning using the official `Microsoft.AspNetCore.Mvc.Versioning` package.
By planning your versioning strategy early, you ensure smooth upgrades for clients and keep your API future-proof.
