Introduction
In modern backend development, especially in ASP.NET Core Web API projects, API versioning is not optional—it is a foundational design decision. As your application evolves, you will inevitably change response formats, add fields, deprecate endpoints, or improve performance. Without versioning, even a small change can break mobile apps, frontend clients, or third-party integrations already consuming your API.
For example, imagine an e-commerce app where version 1 of the API returns only product name and price. Later, you add discount and stock fields in version 2. If you change the existing API directly, older mobile apps may crash because they are not expecting new fields or structure.
This is where API versioning in ASP.NET Core becomes critical for backward compatibility, scalability, and safe feature rollout.
In this article, you will learn in detail:
What API versioning is and why it matters
How to implement URL versioning in ASP.NET Core
How to implement query string versioning
How to implement header versioning
Real-world use cases and architecture decisions
Advantages and disadvantages of each approach
What is API Versioning?
API versioning is the practice of maintaining multiple versions of an API simultaneously so that existing clients continue to work even after updates are made.
Real-Life Analogy
Think of API versioning like Android app updates:
Some users are still on version 1.0
Others update to version 2.0
Both versions must work without breaking
Similarly, your backend API must support both old and new clients.
Why API Versioning is Important in Real Projects
In real-world enterprise systems and cloud-based applications, API versioning solves multiple critical problems:
Prevents breaking changes in production
Supports gradual rollout of new features
Enables A/B testing of APIs
Helps maintain compatibility with multiple client platforms (mobile, web, IoT)
Real-World Scenario
A fintech application releases a new transaction API with enhanced security. Older mobile apps still rely on the previous structure. Without versioning, all users would be forced to update the app immediately—which is not practical.
Step 1: Install Required Package
To enable API versioning in ASP.NET Core, install the official package:
dotnet add package Microsoft.AspNetCore.Mvc.Versioning
This package provides built-in support for handling different API versions efficiently.
Step 2: Configure API Versioning in ASP.NET Core
Update Program.cs with detailed configuration:
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
});
Explanation
DefaultApiVersion: Sets fallback version (v1.0)
AssumeDefaultVersionWhenUnspecified: Prevents errors if version is missing
ReportApiVersions: Adds supported versions in response headers
Example Response Header
api-supported-versions: 1.0, 2.0
URL Versioning in ASP.NET Core
What is URL Versioning?
In this approach, the API version is part of the URL path.
Example:
/api/v1/products
/api/v2/products
Implementation
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/products")]
[ApiController]
public class ProductsController : ControllerBase
{
[HttpGet]
public IActionResult Get()
{
return Ok("Products from Version 1");
}
}
Version 2:
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/products")]
[ApiController]
public class ProductsV2Controller : ControllerBase
{
[HttpGet]
public IActionResult Get()
{
return Ok("Products from Version 2 with enhancements");
}
}
Real-World Use Case
Public APIs (like payment gateways or e-commerce APIs) commonly use URL versioning because it is explicit and easy to debug.
Advantages
Disadvantages
Query String Versioning in ASP.NET Core
What is Query String Versioning?
Version is passed as a query parameter in the URL.
Example:
/api/products?api-version=1.0
Configuration
options.ApiVersionReader = new QueryStringApiVersionReader("api-version");
Real-World Use Case
Used in systems where modifying URL paths is difficult (e.g., legacy systems or shared endpoints).
Advantages
Disadvantages
Header Versioning in ASP.NET Core
What is Header Versioning?
Version is passed through HTTP headers instead of URL.
Example:
X-Version: 1.0
Configuration
options.ApiVersionReader = new HeaderApiVersionReader("X-Version");
Real-World Use Case
Used in enterprise internal APIs or microservices where clean URLs are required.
Advantages
Keeps URLs clean
Flexible and scalable
Disadvantages
Difference Between URL, Query String, and Header Versioning
| Feature | URL Versioning | Query String Versioning | Header Versioning |
|---|
| Visibility | High | Medium | Low |
| Ease of Testing | Easy | Easy | Moderate |
| Caching Support | Strong | Weak | Moderate |
| Best Use Case | Public APIs | Legacy systems | Internal APIs |
Combining Multiple Versioning Strategies
In real-world ASP.NET Core applications, you can combine multiple strategies:
options.ApiVersionReader = ApiVersionReader.Combine(
new QueryStringApiVersionReader("api-version"),
new HeaderApiVersionReader("X-Version")
);
This ensures flexibility for different types of clients.
Before vs After Versioning (Real Scenario)
Before
API changes break production apps
No backward compatibility
Frequent hotfixes required
After
Advantages of API Versioning
Enables backward compatibility
Supports safe feature evolution
Improves API lifecycle management
Helps in debugging and monitoring
Disadvantages
Increased maintenance effort
Multiple versions to manage
Code duplication in some cases
Best Practices for API Versioning
Use URL versioning for public APIs
Avoid breaking changes in the same version
Deprecate old versions gradually
Maintain clear API documentation
Summary
API versioning in ASP.NET Core is a critical practice for building scalable, maintainable, and production-ready APIs. By implementing URL versioning, query string versioning, and header versioning, developers can ensure backward compatibility while continuously evolving their applications. Each approach serves different use cases—URL versioning is best for public APIs, query string works well in legacy systems, and header versioning fits internal architectures. Choosing the right strategy, or combining them, helps organizations deliver updates safely without disrupting existing users.