Hi Everyone, Today, we will understand the concept of API Versioning. To Follow the REST Standard guidelines for API development, check out this blog rest-api-standard-for-apis-development.
In this article, we will create the REST API supporting multiple versions in .NET 8.
Introduction
API versioning is the practice of managing changes to your API in a structured and predictable manner. It helps maintain compatibility with existing clients while enabling the introduction of new functionality. In this article, we'll explore what API versioning is, why it's important, and various strategies for implementing it effectively.
Why is API Versioning important?
- Backward Compatibility: Ensures existing clients can continue to use the API without breaking when new changes are introduced.
- Continuous Improvement: Allows developers to make improvements or add new features to the API without disrupting current users.
- Smooth Transition: Provides a clear path for clients to transition from one version of the API to another.
- Error Management: Helps identify issues more effectively when problems arise from changes.
Key strategies for API versioning
There are several common strategies to implement API versioning, each with its own advantages and trade-offs.
- URI Path Versioning: In this strategy, the version number is included in the URI path, for example.
- Version 1: https://api.example.com/v1/users
- Version 2: https://api.example.com/v2/users
- Query Parameter Versioning: In this approach, the version number is included as a query parameter in the URL. For example.
- https://api.example.com/users?version=1
- https://api.example.com/users?version=2
- Header Versioning: Here, the version number is included in the HTTP headers, for example.
GET /users HTTP/1.1 Host: api.example.com X-API-Version:2 - Content Negotiation (Media Type Versioning): This strategy uses the Accept header to specify the version of the API, for example.
GET /users HTTP/1.1 Host: api.example.com Accept: application/json; version=1
Sample project in .NET 8 (C#) Web-API
Step 1. Install the Necessary Package Add the Microsoft.AspNetCore.Mvc.Versioning package.
dotnet add package Microsoft.AspNetCore.Mvc.Versioning
Step 2. Configure API Versioning in Startup.cs Modify the Startup.cs file to include API versioning.
using Microsoft.AspNetCore.Mvc.Versioning;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Options;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options =>
{
// Define Swagger documents for different versions
options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo
{
Version = "v1",
Title = "My API v1",
Description = "API documentation for version 1"
});
options.SwaggerDoc("v2", new Microsoft.OpenApi.Models.OpenApiInfo
{
Version = "v2",
Title = "My API v2",
Description = "API documentation for version 2"
});
// Use the ConflictingActionsResolver workaround
options.ResolveConflictingActions(apiDescriptions =>
{
// Your conflict resolution strategy here
// Example: Choose the first action
return apiDescriptions.First();
});
// Add more versions as needed
});
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0); // Default version: 1.0
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
// Combine multiple versioning schemes
options.ApiVersionReader = ApiVersionReader.Combine(
new QueryStringApiVersionReader("version"),
new UrlSegmentApiVersionReader(),
new HeaderApiVersionReader("X-API-Version"),
new MediaTypeApiVersionReader("version")
);
});
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI(options =>
{
// Define the endpoints for each version
options.SwaggerEndpoint("/swagger/v1/swagger.json", "My API v1");
options.SwaggerEndpoint("/swagger/v2/swagger.json", "My API v2");
});
}
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();
Step 3. Create the Users Controller Implement a UsersController that supports multiple versioning methods. Start with versions 1.0 & 2.0.


Join the conversation! Your thoughts help the community grow.