-
Notifications
You must be signed in to change notification settings - Fork 712
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:
This example demonstrates API versioning using all non-URL segment methods.
[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!";
}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.
[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!";
}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 );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).
- Home
- Quick Starts
- Version Format
- Version Discovery
- Version Policies
- How to Version Your Service
- API Versioning with OData
- Configuring Your Application
- Error Responses
- API Documentation
- Extensions and Customizations
- Known Limitations
- FAQ
- Examples