API Versioning in ASP.NET Core: Best Practices for Building Maintainable APIs
API versioning in ASP.NET Core is an essential technique for maintaining backward compatibility while allowing APIs to evolve over time. As applications grow and new features are introduced, existing clients should continue working without disruption. Proper API versioning enables developers to release improvements safely and support multiple versions simultaneously.
Modern web applications, mobile apps, and third-party integrations rely heavily on APIs. Breaking changes can affect consumers and create maintenance challenges. By implementing API versioning in ASP.NET Core correctly, developers can deliver updates without forcing all clients to upgrade immediately.
Why API Versioning is Important
As business requirements change, APIs need additional endpoints, modified response structures, or improved functionality. Without versioning, introducing these changes could break existing applications. API versioning allows multiple versions to coexist and gives consumers enough time to migrate to newer releases.
Benefits of API versioning include backward compatibility, smoother deployments, easier maintenance, better developer experience, and reduced risks during upgrades.
Common API Versioning Strategies
1. URL Versioning
URL versioning places the version number directly in the endpoint URL. It is one of the most popular approaches because it is simple and easy to understand.
https://api.example.com/api/v1/products https://api.example.com/api/v2/products
URL versioning is easy to implement, cache-friendly, and highly visible to API consumers.
2. Query String Versioning
Query string versioning uses a parameter to specify the API version.
https://api.example.com/api/products?api-version=1.0
This approach keeps URLs clean and allows flexibility, although it is less explicit compared to URL versioning.
3. Header Versioning
In header versioning, clients specify the version in HTTP headers.
api-version: 2.0
Header versioning keeps URLs unchanged and separates version information from resources, but it can be less intuitive for consumers.
4. Media Type Versioning
Media type versioning embeds the version inside the Accept header.
Accept: application/json;version=2.0
Although powerful, media type versioning is more complex and often used in enterprise APIs.
Installing API Versioning Package
Microsoft provides official support for API versioning through NuGet packages. Install the package using the .NET CLI.
dotnet add package Asp.Versioning.Mvc
After installation, configure versioning services in Program.cs.
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1,0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
});
This configuration defines version 1.0 as the default and reports supported API versions in response headers.
Creating Versioned Controllers
Controllers can support multiple versions by using the ApiVersion attribute.
using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;
[ApiController]
[Route("api/v{version:apiVersion}/products")]
[ApiVersion("1.0")]
public class ProductsController : ControllerBase
{
[HttpGet]
public IActionResult Get()
{
return Ok("Products from API V1");
}
}
Creating a second version is straightforward.
[ApiController]
[Route("api/v{version:apiVersion}/products")]
[ApiVersion("2.0")]
public class ProductsV2Controller : ControllerBase
{
[HttpGet]
public IActionResult Get()
{
return Ok("Products from API V2");
}
}
Supporting Multiple Versions in One Controller
ASP.NET Core allows a controller to support more than one version.
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class OrdersController : ControllerBase
{
}
This approach reduces code duplication and simplifies maintenance when only a few actions differ between versions.
Versioning Using Query Strings
If query string versioning is preferred, configure the ApiVersionReader.
builder.Services.AddApiVersioning(options =>
{
options.ApiVersionReader =
new QueryStringApiVersionReader("api-version");
});
Clients can then request different versions through query parameters.
GET /api/products?api-version=2.0
Versioning with Headers
Header versioning separates version information from URLs.
builder.Services.AddApiVersioning(options =>
{
options.ApiVersionReader =
new HeaderApiVersionReader("api-version");
});
Clients specify versions using custom headers, making endpoint URLs cleaner and more RESTful.
Deprecating API Versions
Over time, old versions should be deprecated to reduce maintenance overhead. ASP.NET Core allows marking versions as deprecated.
[ApiVersion("1.0", Deprecated = true)]
Consumers receive version information in response headers, helping them migrate to newer versions before old APIs are removed.
Best Practices for API Versioning in ASP.NET Core
Use Semantic Versioning
Follow semantic versioning principles where major versions represent breaking changes and minor versions represent backward-compatible improvements.
Avoid Breaking Existing Clients
Maintain older versions until clients have sufficient time to migrate. Sudden removals can impact applications and business operations.
Document All Versions
Swagger and OpenAPI documentation should clearly indicate supported versions and deprecated endpoints.
Choose One Strategy Consistently
Using multiple versioning mechanisms can confuse consumers. Select one approach and apply it consistently across the API.
Communicate Deprecation Plans
Provide notices and migration guides before retiring old versions.
Integrating API Versioning with Swagger
Swagger simplifies API testing and documentation. Version-specific Swagger documents improve discoverability and help developers understand differences between releases.
builder.Services.AddEndpointsApiExplorer(); builder.Services.AddSwaggerGen();
Combining Swagger with API versioning creates a better developer experience and reduces integration issues.
Real-World Example
Suppose an e-commerce platform exposes a product endpoint. Version 1 returns product names and prices. Later, version 2 introduces categories and stock information. Existing mobile applications continue using version 1 while newer applications consume version 2. This gradual migration avoids service interruptions and improves compatibility.
Common Mistakes to Avoid
- Changing response formats without versioning.
- Removing endpoints abruptly.
- Using inconsistent version numbering.
- Supporting too many obsolete versions.
- Failing to document changes.
- Ignoring client migration requirements.
Useful Resources
You can learn more about API development from these related articles:
Official Microsoft documentation provides complete guidance on API versioning and ASP.NET Core development.
Microsoft ASP.NET Core Web API Documentation
Conclusion
API versioning in ASP.NET Core plays a critical role in building scalable and maintainable applications. It enables teams to introduce new features without breaking existing clients and supports long-term API evolution. Whether using URL versioning, query strings, headers, or media types, selecting the right strategy and following best practices ensures reliable integrations and a better experience for API consumers.
By implementing API versioning in ASP.NET Core properly, development teams can maintain compatibility, simplify upgrades, and deliver continuous improvements confidently.
