API Versioning in ASP.NET Core

What is API Versioning

API versioning is a technique that allows you to make changes and enhancements to your API without breaking existing client applications.

Why we need it ?

It gives us three main benefits and those are the reasons why need it:

• Backward Compatibility:

  Different versions of your API can coexist, ensuring that older clients continue to function as expected.

• Maintainability:

  As your API evolves over time, versioning helps you keep track of changes and manage different iterations of the API.

• Granular Control:

  API versioning provides granular control over which version of an endpoint a client application can access. This enables you to selectively expose new features to specific clients while ensuring that others continue to use older versions of the API.

  Enough theory let’s dive into action !!!!

Implementation of API Versioning

It consists on three simple steps:

1/ Install Nuget Package:

Microsoft.AspNetCore.Mvc.Versioning

2/ Configure Program.cs:

builder.services.AddApiVersioning is enough to enable versioning.

Then we can set options of service according our needs.

builder.Services.AddApiVersioning(options =>
{
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ReportApiVersions = true;
});

First two options set the default version if user does not specify and second line makes sure which version is default.

ReportApiVersion tells us that which versions are supported to client, to enable it we need to set its value to true.

Note : It is good to read these values from appsetting instead of hard coding.

3/ Add versions on controllers: Tell controller that we are going to enable versioning here by using ApiVersion attribute.

Then by using MaToApiVersion specify that for which versions this method/endpoint is available.

[ApiController]
[Route("[controller]")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class WeatherForecastController : ControllerBase
{
    [HttpGet("GetVersion"), MapToApiVersion("2.0")]
    public string GetBetaVersion()
    {
        return "Beta Version: 2.0";
    }
}

4/ How to call it via Postman By adding api-version in query string parameter we can define our version

https://localhost:7149/WeatherForecast/GetVersion?api-version=2.0

By default api version is read from query string parameter but we can add multiple options or even single as well. For multiple options add these lines of code in your service.

builder.Services.AddApiVersioning(options =>
{
options.AssumeDefaultVersionWhenUnspecified = true; options.DefaultApiVersion = new ApiVersion (1, 0);
options. ApiVersionReader = ApiVersionReader.Combine(
new QueryStringApiVersionReader("api-version"), /
});

That’s all for this Saturday, Hakuna Matata :)