Introduction
When you build a Web API in ASP.NET Core, your API will evolve over time. You may add new features, change response formats, or improve existing endpoints. But what happens to existing users who are already using your API?
This is where API versioning becomes very important.
API versioning allows you to maintain multiple versions of your API so that old clients continue to work while new clients can use updated features.
In this article, you will learn how to implement API versioning in ASP.NET Core Web API in a simple, practical, and step-by-step way.
What is API Versioning?
API versioning is a technique that allows different versions of your API to exist at the same time.
In simple words:
Old users continue using version 1
New users can use version 2
Your application remains stable and backward compatible
This is very important in real-world applications where breaking changes can affect thousands of users.
Why API Versioning is Important
API versioning helps you:
Avoid breaking existing clients
Introduce new features safely
Maintain backward compatibility
Manage API lifecycle effectively
Without versioning, even small changes can break applications that depend on your API.
Types of API Versioning in ASP.NET Core
There are multiple ways to implement API versioning:
Let’s understand each one in simple terms.
URL Versioning
Version is included in the URL.
Example:
/api/v1/products
/api/v2/products
This is the easiest and most widely used approach.
Query String Versioning
Version is passed as a query parameter.
Example:
Header Versioning
Version is passed in request headers.
Example:
Media Type Versioning
Version is specified in the Accept header.
Example:
Prerequisites
Before starting, ensure you have:
Step 1: Install API Versioning Package
Run the following command:
dotnet add package Microsoft.AspNetCore.Mvc.Versioning
This package provides built-in support for API versioning.
Step 2: Configure API Versioning in Program.cs
Open your Program.cs file and add the following configuration:
builder.Services.AddApiVersioning(options =>
{
options.AssumeDefaultVersionWhenUnspecified = true;
options.DefaultApiVersion = new ApiVersion(1, 0);
options.ReportApiVersions = true;
});
Explanation:
AssumeDefaultVersionWhenUnspecified → Uses default version if not provided
DefaultApiVersion → Sets default version
ReportApiVersions → Returns supported versions in response headers
Step 3: Add Versioning to Controller
Now, define API version in your controller.
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
public class ProductsController : ControllerBase
{
[HttpGet]
public IActionResult Get()
{
return Ok("Products from API Version 1");
}
}
This controller handles version 1 of the API.
Step 4: Create Version 2 of API
Now, let’s create a second version.
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("2.0")]
public class ProductsV2Controller : ControllerBase
{
[HttpGet]
public IActionResult Get()
{
return Ok("Products from API Version 2 with new features");
}
}
Now you have two versions running side by side.
Step 5: Using Multiple Versions in Same Controller
You can also support multiple versions in a single controller.
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class OrdersController : ControllerBase
{
[HttpGet]
[MapToApiVersion("1.0")]
public IActionResult GetV1()
{
return Ok("Orders from Version 1");
}
[HttpGet]
[MapToApiVersion("2.0")]
public IActionResult GetV2()
{
return Ok("Orders from Version 2");
}
}
This helps reduce code duplication.
Step 6: Configure Query String Versioning
If you want to use query string versioning:
options.ApiVersionReader = new QueryStringApiVersionReader("version");
Now API can be called like:
/api/products?version=1
Step 7: Configure Header Versioning
options.ApiVersionReader = new HeaderApiVersionReader("api-version");
Request example:
api-version: 1
Step 8: Best Practices for API Versioning
Follow these best practices:
Use clear version naming (v1, v2)
Avoid breaking changes in existing versions
Deprecate old versions gradually
Document all versions properly
Use URL versioning for simplicity
Step 9: Real-World Example
Imagine an e-commerce API:
Version 1:
Version 2:
Old apps continue using v1, while new apps use v2.
This ensures smooth upgrades without breaking existing users.
Advantages of API Versioning
Summary
API versioning in ASP.NET Core Web API is essential for building scalable and future-proof applications. It allows you to introduce changes without breaking existing clients. By using built-in versioning features, you can easily manage multiple API versions using URL, query string, or headers. Following best practices ensures your API remains stable, flexible, and easy to maintain as it evolves.