Deprecating a Service Version

When a service supports multiple API versions, some versions will eventually be deprecated over time. To advertise that one or more API versions have been deprecated, simply decorate your controller with the deprecated API versions. A deprecated API version does not mean the API version is not supported. A deprecated API version means that the version will become unsupported after six months or more.

The following examples illustrate how to specify deprecated API versions depending on which service API versioning approach you selected:

ASP.NET Core

This example demonstrates API versioning using all non-URL segment methods.

Mvc (Core)

[ApiVersion( 2.0 )]
[ApiVersion( 1.0, Deprecated = true )]
[ApiController]
[Route( "api/[controller]" )]
public class HelloWorldController : ControllerBase
{
    [HttpGet]
    public string Get() => "Hello world!"

    [HttpGet, MapToApiVersion( 2.0 )]
    public string GetV2() => "Hello world v2.0!";
}

Minimal APIs

var api = app.NewVersionedApi();
var hello = api.MapGroup( "/api/helloworld" )
               .HasDeprecatedApiVersion( 1.0 )
               .HasApiVersion( 2.0 );

hello.MapGet( "/", () => "Hello world!" );
hello.MapGet( "/", () => "Hello world v2.0!" ).MapToApiVersion( 2.0 );

This example demonstrates API versioning using the URL segment method.

MVC (Core)

[ApiVersion( 2.0 )]
[ApiVersion( 1.0, Deprecated = true )]
[ApiController]
[Route( "api/v{version:apiVersion}/[controller]" )]
public class HelloWorldController : ControllerBase
{
    [HttpGet]
    public string Get() => "Hello world!"

    [HttpGet, MapToApiVersion( 2.0 )]
    public string GetV2() => "Hello world v2.0!";
}

Minimal APIs

var api = app.NewVersionedApi();
var hello = api.MapGroup( "/api/v{version:apiVersion}/helloworld" )
               .HasDeprecatedApiVersion( 1.0 )
               .HasApiVersion( 2.0 );

hello.MapGet( "/", () => "Hello world!" );
hello.MapGet( "/", () => "Hello world v2.0!" ).MapToApiVersion( 2.0 );

Removing a Service

To permanently sunset a service, simply remove that controller or API version from your implementation. The route will no longer be matched. When one or more specific API versions cannot be matched, clients will receive HTTP status code 400 (Bad Request). If no candidate routes match at all, clients will receive HTTP status code 404 (Not Found).