How to Apply API Versioning in ASP.NET Core

API versioning is an essential feature of web development that enables developers to control the versions of their APIs. With versioning, developers can release new features or modify existing ones while maintaining backward compatibility with older versions. In this article, we will discuss how to apply API versioning in ASP.NET Core.

Why Use API Versioning?

API versioning is essential in web development because it allows developers to introduce new features or modify existing ones while maintaining backward compatibility with older versions. This feature ensures that existing clients do not break when new changes are introduced in the API.

For instance, let's say you have a mobile application that relies on an API that provides data for the app. If the API is updated without versioning, it can break the app, and users may stop using it. However, with versioning, the new version can be introduced without breaking the existing version, and users can continue using the app.

How to Apply API Versioning in ASP.NET Core?

ASP.NET Core provides built-in support for versioning APIs. There are two approaches to applying API versioning in ASP.NET Core: URL-based versioning and header-based versioning.

URL-based Versioning:

URL-based versioning is the most straightforward approach to versioning APIs. It involves adding the version number to the URL endpoint. Here's how to implement URL-based versioning in ASP.NET Core:

Step 1: Install the Microsoft.AspNetCore.Mvc.Versioning NuGet package:

Open the Package Manager Console and run the following command:

Install-Package Microsoft.AspNetCore.Mvc.Versioning

Step 2: Configure API versioning:

Open the Startup.cs file and add the following code to the ConfigureServices method:

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

This code configures the API versioning middleware by setting the default version to 1.0, assuming the default version when unspecified, and reporting the API versions.

Step 3: Add versioning to the endpoints:

Open the Controllers and add the following code to the endpoints:

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
public class ValuesController : ControllerBase
{
    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        return new string[] { "value1", "value2" };
    }
}

This code adds the version number to the URL endpoint. In this case, the endpoint is "api/v{version}/values". The version number is specified in the URL segment.

Header-based Versioning:

Header-based versioning involves adding a custom header to the API request. Here's how to implement header-based versioning in ASP.NET Core:

Step 1: Install the Microsoft.AspNetCore.Mvc.Versioning NuGet package:

Open the Package Manager Console and run the following command:

Install-Package Microsoft.AspNetCore.Mvc.Versioning

Step 2: Configure API versioning:

Open the Startup.cs file and add the following code to the ConfigureServices method:

services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = new HeaderApiVersionReader("X-Version");
});

This code configures the API versioning middleware by setting the default version to 1.0, assuming the default version when unspecified, reporting the API versions, and setting the header name to "X-Version".

Step 3: Add versioning to the endpoints:

Open the Controllers and add the following code to the endpoints:

[ApiController]
[Route("api/[controller]")]
public class ValuesController : ControllerBase
{
    [HttpGet]
    [MapToApiVersion("1.0")]
    public ActionResult<IEnumerable<string>> GetV1()
    {
        return new string[] { "value1", "value2" };
    }

    [HttpGet]
    [MapToApiVersion("2.0")]
    public ActionResult<IEnumerable<string>> GetV2()
    {
        return new string[] { "value1", "value2", "value3" };
    }
}

This code adds versioning to the endpoints by using the MapToApiVersion attribute. The GetV1 method is mapped to version 1.0, and the GetV2 method is mapped to version 2.0.

Testing the API Versioning:

To test the API versioning, use a tool like Postman or any web browser.

URL-based versioning:

Send a GET request to "http://localhost:port/api/v1.0/values" to get the response from the version 1.0 API.

Send a GET request to "http://localhost:port/api/v2.0/values" to get the response from the version 2.0 API.

Header-based versioning:

Send a GET request to "http://localhost:port/api/values" with the custom header "X-Version: 1.0" to get the response from the version 1.0 API.

Send a GET request to "http://localhost:port/api/values" with the custom header "X-Version: 2.0" to get the response from the version 2.0 API.

Conclusion:

API versioning is an essential feature in web development that enables developers to introduce new features or modify existing ones while maintaining backward compatibility with older versions. In this article, we have discussed how to apply API versioning in ASP.NET Core using URL-based and header-based versioning. Both approaches are easy to implement, and you can choose the one that best fits your project requirements.