Best practices of API version management in asp.net core

What needs api version control

At the beginning, the system has an api to serve customer A. As the business develops, the system has been upgraded, and this api also needs to be adjusted. However, I still need it to continue to support customer A, so I need to introduce a version to manage it. The behavior of multiple versions of the API is different from each other.

What are the ways to implement api version in asp.net core?

• Based on request parameters
• Based on URL
• Based on request header

Installation package

Microsoft provides independent package support, introduced through the command line or nuget package management tool

Install-Package Microsoft.AspNetCore.Mvc.Versioning

Enable the api version in the startup class

Define extension method, enable configuration

public static class ApiVersioningExtensions
    {
        public static IServiceCollection AddApiVersioning(this IServiceCollection services)
        {
            services.AddApiVersioning(config =>
            {
                // 指定默认版本
                config.DefaultApiVersion = new Microsoft.AspNetCore.Mvc.ApiVersion(1, 0);
                // 如果客户端没有在请求中指定api版本，则使用默认版本
                config.AssumeDefaultVersionWhenUnspecified = true;
                // 公布api版本
                config.ReportApiVersions = true;
            });

            return services;
        }
    }

Optimal directory structure

Put different versions of the api in different directories, and the responsibilities are more clear

How to implement the api version based on url

The request version is clearly known in the url, I personally prefer this

https://xxxx/api/v1/user

https://xxxx/api/v2/user

1.0 API definition

namespace ApiVersioning.Controllers.V1
{
    [Route("api/v{version:apiVersion}/[controller]")]
    [ApiController]
    [ApiVersion("1.0")]
    public class UserController : ControllerBase
    {
        [HttpGet]
        public string Get()
        {
            return "use from api v1";
        }
    }
}

2.0 API definition

namespace ApiVersioning.Controllers.V2
{
    [Route("api/v{version:apiVersion}/[controller]")]
    [ApiController]
    [ApiVersion("2.0")]
    public class UserController : ControllerBase
    {
        [HttpGet]
        public string Get()
        {
            return "use from api v2";
        }
    }
}

Run to see the effect

Query-based api version

Splice the version number into the request parameters

https://xxxx/api/user?api-version=1

https://xxxx/api/v2/user?api-version=2

You only need to make simple adjustments to the api controller. Modify the [Route("api/v{version:apiVersion}/[controller]")] of each controller to [Route("api/[controller]")].

Execution effect

API version based on http request header

Modify the startup class and add the configuration item config.ApiVersionReader = new HeaderApiVersionReader("x-api-version");

namespace ApiVersioning
{
    public static class ApiVersioningExtensions
    {
        public static IServiceCollection AddApiVersioning(this IServiceCollection services)
        {
            services.AddApiVersioning(config =>
            {
                // 指定默认版本
                config.DefaultApiVersion = new Microsoft.AspNetCore.Mvc.ApiVersion(1, 0);
                // 如果客户端没有在请求中指定api版本，则使用默认版本
                config.AssumeDefaultVersionWhenUnspecified = true;
                // 导出api版本
                config.ReportApiVersions = true;
                // 支持HTTP Header
                config.ApiVersionReader = new HeaderApiVersionReader("x-api-version");
            });

            return services;
        }
    }
}

Open postman to run separately

Sample code

https://gitee.com/dx1024/full-project/tree/api-versioning/src/ApiVersioning