Asp-Net-Core Development Notes: API Version Management

Preface

For Web API applications, as time progresses and requirements increase or change, APIs will inevitably encounter the need for upgrades. In fact, Web API applications should consider API versioning from the very beginning of their creation. Business adjustments, feature additions, endpoint removals and renaming, changes in endpoint parameters, as well as adding, removing, or modifying entity properties can all alter API functionality, thus resulting in version changes.

Most existing resources use the Microsoft.AspNetCore.Mvc.Versioning package, but upon actual use, I found that this package has long been discontinued. Microsoft's official documentation also seems to lack information on this. However, the package's NuGet page indicates it has been replaced by the new Asp.Versioning.Mvc package. It turns out Microsoft's renaming department has been at it again—my apologies for the oversight! 😂

Fortunately, this new package has detailed documentation on GitHub, but the speed of renaming is quite astonishing. In order to implement this functionality, I took quite a few detours. 😂

OK, this article is based on .Net6.0 and uses AspNetCore WebApi as an example to introduce the process of incorporating API version management.

Basics

There are two ways to specify a version: you can either use the [ApiVersion] attribute or the version convention approach. Once different versions of an API interface are defined, clients can access a specific version of the API through several methods as follows:

• Using the URL path, e.g., api/v1.0/values
• Using a query string, e.g., api/values?api-version=1.0
• Using a custom HTTP header
• Using a Media Type parameter, e.g., Accept: application/json;v=2.0

The default method in ASP.NET Core MVC is using a query string, with the parameter name api-version. The specific method to use is determined by the server (configured using the ApiVersionReader property introduced below), and it can be one of the methods or multiple methods used simultaneously.

The API version format consists of a major version number and a minor version number, and it can also include two optional parts: a version group and a status.

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

The version group format is YYYY-MM-DD and serves to logically group API interfaces, while the status indicates the current state of the version, such as Alpha, Beta, and RC. Here are some common version formats:

• /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

This article uses the format /api/v1/foo.

Installing Dependencies

You need to install these two NuGet packages:

• Asp.Versioning.Mvc
• Asp.Versioning.Mvc.ApiExplorer

Register Services

Edit the Program.cs file

builder.Services.AddApiVersioning(options => {
  options.DefaultApiVersion = new ApiVersion(1, 0);
  options.AssumeDefaultVersionWhenUnspecified = true;
  options.ReportApiVersions = true;
  options.ApiVersionReader = ApiVersionReader.Combine(
    new UrlSegmentApiVersionReader(),
    new HeaderApiVersionReader("x-api-version"),
    new MediaTypeApiVersionReader("ver")
  );
})
  .AddMvc()
  .AddApiExplorer(options => {
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
  });

The code above does the following:

• DefaultApiVersion sets the default version to 1.0.
• AssumeDefaultVersionWhenUnspecified uses the default version when no version is specified.
• ReportApiVersions adds available API versions to the response headers.
• ApiVersionReader defines that API version information can be retrieved from three places: the URL and two request headers.
• GroupNameFormat specifies the format for version names, see the table below for details.
• SubstituteApiVersionInUrl is set to true because URL-based versioning is being used.

API Version Format Strings

In this article, I use the 'v'VVV format

Setting Up API Versions

The example interface has two versions:

• /api/v1/demo/test
• /api/v2/demo/test

Create two directories under the Controller, v1 and v2, then create a Controller in each respectively.

Here's the code for Controllers/v1/DemoController.cs:

[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion(1.0)]
[ApiController]
public class DemoController : ControllerBase {
  [HttpGet("[action]")]
  public ApiResponse Test() {
    return ApiResponse.Ok("version=1.0");
  }
}

The other version of the interface Controllers/v2/DemoController.cs:

[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion(2.0)]
[ApiController]
public class DemoController : ControllerBase {
  [HttpGet("[action]")]
  public ApiResponse Test() {
    return ApiResponse.Ok("version=2.0");
  }
}

As you can see, to distinguish between different versions of the interface, you only need to add the [ApiVersion(2.0)] attribute.

Since I want to use the URL to select different versions of the interface, the route needs to be configured as "api/v{version:apiVersion}/[controller]".

If you don't include the version number in the URL, you can also pass it using a request parameter, for example, /api/demo/test?api-version=1.0.

This can be configured in the ApiVersionReader attribute.

Configuring Swagger

Swagger has essentially become the standard for API documentation, but I've noticed many articles overlook this part. (Fortunately, the official documentation didn't forget.)

First, create a configuration class.

public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions> {
  readonly IApiVersionDescriptionProvider provider;

  public ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider) =>
    this.provider = provider;

  public void Configure(SwaggerGenOptions options) {
    foreach (var description in provider.ApiVersionDescriptions) {
      options.SwaggerDoc(
        description.GroupName,
        new OpenApiInfo() {
          Title = $"Example API {description.ApiVersion}",
          Version = description.ApiVersion.ToString(),
        });
    }
  }
}

Registering Services

builder.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();

Configuring Middleware

app.UseSwagger();
app.UseSwaggerUI(options => {
    foreach (var description in app.DescribeApiVersions()) {
        var url = $"/swagger/{description.GroupName}/swagger.json";
        var name = description.GroupName.ToUpperInvariant();
        options.SwaggerEndpoint(url, name);
    }
});

Effects & Testing

Done. Access the swagger documentation, and in the upper right corner, the API grouping (接口分组) shows different versions.

Request https://localhost:7053/api/v1/Demo/Test

The API returns:

{
  "statusCode": 200,
  "successful": true,
  "message": "version=1.0",
  "data": null,
  "errorData": null
}

Request https://localhost:7053/api/v2/Demo/Test

The API returns:

{
  "statusCode": 200,
  "successful": true,
  "message": "version=2.0",
  "data": null,
  "errorData": null
}

Not bad~ 😃

References

• https://github.com/dotnet/aspnet-api-versioning/wiki