ASP.NET Core API versioning

• ASP.NET Core MVC
• ASP.NET Core logging with Serilog
• ASP.NET Core managed config
• ASP.NET Core MVC with /api/-area
• ASP.NET Core API versioning
• ASP.NET Core API with Swagger UI
• ASP.NET Core EF in separate project
• ASP.NET Core AutoMapper
• ASP.NET Core response cache
• ASP.NET Core memory cache
• ASP.NET Core TypeScript

With API’s often changing over time you may want to plan for versioning early on. ASP.NET Core has a library that makes versioning API a bit easier. By tagging controllers and actions with version number one can run multiple versions simultaneously.

Install

Install-Package Microsoft.AspNetCore.Mvc.Versioning

Implement

In Startup.cs ConfigureServices:

services.AddApiVersioning();

If you want to keep some URL’s without versioning, or have an existing API that is already in use then you can configure default versioning by adding:

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

Use

Versions can be in format:

• [Version Group.]<Major>.<Minor>[-Status]
• <Version Group>[<Major>[.Minor]][-Status]

Examples:

• /api/foo?api-version=1.0
• /api/foo?api-version=2.0-Alpha
• /api/foo?api-version=2015-05-01.3.0
• /api/v1/foo
• /api/v2.0-Alpha/foo
• /api/v2015-05-01.3.0/foo

Tag your controller with [ApiVersion()]. Note that you can use the tags multiple times if a controller has multiple versions. You can also make a service version neutral by tagging it with [ApiVersionNeutral].

Since we are using api area we also add version string to [Route] between api and controller name. But this would notwork with “default version” as far as I can see.

    [Route("api/v{version:apiVersion}/[controller]")]
    [ApiVersion("1.0")]
    [ApiVersion("1.1")]
    [ApiController]
    public class TestController : ControllerBase
    {
...

You can map individual methods within the controller, here using the example of “Dual”:

[Route("Dual")]
[HttpGet]
[MapToApiVersion("1.0")]
public string DualGet1()
{
    return "You got version 1.0";
}

[Route("Dual")]
[HttpGet]
[MapToApiVersion("2.0")]
public string DualGet2()
{
    return "You got version 2.0";
}