Implementation of ASP. NET Core3. x API Version Control

Preface

Generally speaking, we should only consider version control when we need to change our API, but I don't think we should wait until then to implement it. We should have a version strategy. We should formulate our strategy from the time of our application development, and we should follow this strategy for development.

In fact, we can control our API version in many ways. In fact, there is no best way to control the version, which depends entirely on the users we are facing.

API Versioning Type

Install version control package

Install-Package Microsoft.AspNetCore.Mvc.Versioning

Version control can be achieved by setting the version in the ConfigureServices method in Startup. cs, and setting the version through features in the controller.

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

options. DefaultApiVersion = new ApiVersion (1, 0): This setting is not required, because it is set to 1.0 by default, but it is a good habit to declare it explicitly. Of course, DefaultApiVersion will add the default [ApiVersion ("1.0")] to the controller, which means it will implicitly bind the API version, but it is recommended to explicitly set it for our convenience or convenience. options. AssumeDefaultVersionWhenUnspecified = true: Default API versioning requires its property set to true before it can be turned on options. ReportApiVersions = true: It is disabled by default, and when this option is enabled, the response from our API endpoint will come with a header telling our client which version is supported or not recommended (api-supported-versions: 1.1, 2.0, api-deprecated-versions: 1.0)

There are four version control methods provided by default:

String parameter Request headers through HTTP URL mode Media Type (Media Type)

The default method is to use a query string parameter named api-version. We can also define a version control rule ourselves.

API Version Constraint Mode

String parameter form

services.AddApiVersioning(options => 
  options.ApiVersionReader = new QueryStringApiVersionReader("v"));

HTTP Request Header

services.AddApiVersioning(options => 
  options.ApiVersionReader = new HeaderApiVersionReader("api-version"));

Combination mode

services.AddApiVersioning(options => {
  options.ApiVersionReader = ApiVersionReader.Combine(
    new QueryStringApiVersionReader("v"),
    new HeaderApiVersionReader("v"));});

URL mode

services.AddApiVersioning(options => options.ApiVersionReader = 
  new UrlSegmentApiVersionReader());

We can change the parameter name that represents the version (for example, in the query string method above, we use the letter v instead of the default api-version).

Add version information to controllers and methods

After selecting a versioning strategy and configuring it in the ConfigureServices method, we can begin versioning the API endpoint, and we can apply these properties to the controller and method.

The default of the controller may not have any API version attributes, and the default API version is implicitly configured. The default configuration uses a value of 1.0. Annotating our controller with the [ApiVersion ("1.0")] attribute means that the controller supports API version 1.0 The controller can support multiple API versions. Simply [ApiVersion (...)] applies multiple attributes on the controller To distinguish between the multiple versions supported by the controller, we annotate the controller methods with the [MapToApiVersion ()] attribute.

If you want to use the URL path, you can refer to the following code snippet:

[Route("api/v{version:apiVersion}/[controller]")]

API controller deactivated, we just need to set

[ApiVersion("1.0", Deprecated = true)]

All API version information can be obtained in the following ways

var apiVersion = HttpContext.GetRequestedApiVersion();

Of course, he also supports model binding, and we can also obtain it in the form of model

 [HttpGet]
  public string Get(ApiVersion apiVersion) => $"Controller = {GetType().Name}\nVersion = {apiVersion}";
  }

API Version Constraints

In addition to specifying our version on the method and controller, we can use another way

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

0

Looking at the above code, we can see that we configured the version of HomeController here, which makes it convenient for us to manage our version centrally.

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

1

You can use both API version constraints and version control properties.

Of course, we can also customize constraints, starting with. NET Core 3.0, with an IControllerConvention interface for this purpose.

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

2

Of course, we can also constrain through interfaces in different namespaces

options.Conventions.Add(new VersionByNamespaceConvention());

For example, the following file form

api/v1/UsersController
api/v2/UsersController
api/v2_1/UsersController

The mapped path is as follows

api/1.0/users
api/2.0/users
api/2.1/users