How to Implement Versioning in ASP.NET Core Web API

It helps maintain support for different client versions, whether they are using older or newer API versions. As different clients may depend on different API versions, versioning ensures that you can upgrade your API without breaking existing users.

To get started with API versioning in your ASP.NET Core project, install the Microsoft.AspNetCore.Mvc.Versioning NuGet package.

Right-click the project in Solution Explorer, select "Manage NuGet Packages," and install the Microsoft.AspNetCore.Mvc.Versioning package from the NuGet Package Manager.

Alternatively, you can install it via the NuGet Package Manager Console using the command:

Install-Package Microsoft.AspNetCore.Mvc.Versioning

How to Enable API versioning

To enable API versioning in your ASP.NET Core project, add services.AddApiVersioning() in the ConfigureServices method. Make sure to include the Microsoft.AspNetCore.Mvc.Versioning namespace.

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
    services.AddApiVersioning();
}

You can set a default API version by configuring it in the AddApiVersioning method.

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
    services.AddApiVersioning(v =>
    {
        v.ReportApiVersions = true;
        v.AssumeDefaultVersionWhenUnspecified = true;
        v.DefaultApiVersion = new ApiVersion(1, 0);
    });
}

Versioning using QueryString Parameter

Take a look at the following API example:

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

You can access this API by including the version in the query string, like so: https://localhost:51867/api/values?api-version=2.0. Be sure to replace the port number with the one used by IIS Express on your system.

Versioning using routes

In route-based versioning, the API version is specified directly in the URL.

Consider the following API example:

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiController]
public class ValuesController : ControllerBase
{
    // GET api/values
    [HttpGet]
    public ActionResult<string> Get()
    {
       return "Hello World";
    }
}

To access the Get method of this API, use the following URL: https://localhost:51867/api/v1.0/values.

Ignore API versioning

In some cases, you may have APIs that do not require versioning. For these APIs, you can bypass versioning by using the [ApiVersionNeutral] attribute.

[ApiVersionNeutral]
[Route("api/[controller]")]
[ApiController]
public class AboutController : ControllerBase
{
    [HttpGet]
    public ActionResult<string> Get()
    {
        return "This is a version-neutral API.";
    }
}

In this case, the AboutController is marked with the [ApiVersionNeutral] attribute, meaning it won't require any versioning, and the API will be accessible without specifying a version.