Introduction
As APIs evolve, new features, bug fixes, and business requirements often require changes to existing endpoints. However, modifying APIs without a versioning strategy can break existing client applications.
API Versioning helps developers introduce changes while maintaining backward compatibility for existing consumers.
In this article, you'll learn why API versioning is important, common versioning approaches, best practices, and mistakes to avoid in ASP.NET Core applications.
Why API Versioning Matters
Imagine an API endpoint:
/api/products
Version 1 returns:
{
"id": 1,
"name": "Laptop"
}
Later, Version 2 adds new fields:
{
"id": 1,
"name": "Laptop",
"category": "Electronics"
}
Without proper versioning, existing applications may stop working correctly.
Versioning allows both versions to coexist safely.
Common API Versioning Strategies
URL Versioning
The version is included in the URL.
/api/v1/products
/api/v2/products
This is the most popular and easiest approach.
Query String Versioning
The version is passed as a query parameter.
/api/products?api-version=1.0
Simple to implement but less visible.
Header Versioning
The version is specified in request headers.
api-version: 1.0
Keeps URLs clean but can be harder to test manually.
Install API Versioning Package
Add the package:
dotnet add package
Asp.Versioning.Mvc
This provides API versioning support for ASP.NET Core.
Configure API Versioning
In Program.cs:
builder.Services
.AddApiVersioning(options =>
{
options.DefaultApiVersion =
new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
});
This enables versioning throughout the application.
Create Versioned Controllers
Version 1:
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsController
: ControllerBase
{
}
Version 2:
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV2Controller
: ControllerBase
{
}
Each version can evolve independently.
Real-World Example
Suppose you're building an e-commerce API.
Version 1:
Get Products
Create Products
Version 2:
Get Products
Create Products
Product Reviews
Older clients continue using Version 1 while newer applications use Version 2.
This prevents breaking changes.
Best Practices
Support Backward Compatibility
Avoid breaking existing clients.
Bad:
Modify Existing Response
Better:
Create New API Version
Version Only When Necessary
Not every change requires a new version.
Examples that usually don't require versioning:
Performance improvements
Internal code changes
Bug fixes
Document All Versions
Clearly document:
Available versions
Deprecation dates
Feature differences
This helps API consumers migrate smoothly.
Use Semantic Versioning
Common format:
v1.0
v2.0
Keep version numbers simple and predictable.
Common Mistakes
Removing Old Versions Too Quickly
Many clients may still depend on older APIs.
Always provide a migration period.
Versioning Too Frequently
Creating a new version for every small change increases maintenance effort.
Version only when breaking changes occur.
Poor Documentation
Clients should easily understand:
Which version to use
What's changed
How to migrate
Lack of documentation creates confusion.
Advantages of API Versioning
API versioning provides several benefits:
Backward compatibility
Safer API evolution
Better client experience
Easier maintenance
Reduced breaking changes
Improved scalability
These benefits become increasingly important as APIs grow.
Conclusion
API Versioning is an essential practice for building maintainable and scalable ASP.NET Core APIs. It allows developers to introduce new features and improvements without disrupting existing clients.
By following best practices such as maintaining backward compatibility, documenting versions properly, and avoiding unnecessary version updates, teams can build APIs that evolve safely over time while providing a stable experience for consumers.