Requiring an explicit service version helps ensure existing clients don’t break, but we also need a way to advertise which service versions are currently supported and which versions are deprecated.

To facilitate this need, services should respond with the api-supported-versions and api-deprecated-versions, which are multi-value HTTP headers that indicate the supported and deprecated API versions, respectively. A deprecated version is still implemented, but is expected to be permanently removed in six months or more. When a version is no longer supported, it should stop being advertised. Additional information can be provided via versioning policies.

Reporting API versions is disabled by default. Service authors can enable this behavior for all services by setting the ApiVersioningOptions.ReportApiVersions to true or scoped to individual services by applying the [ReportApiVersions] attribute or the ReportApiVersions() convention.

Service authors might also choose to implement the OPTIONS method so that clients and tooling can interrogate which API versions their service supports. An example in ASP.NET Web API this would look like:

using static Microsoft.AspNetCore.Http.HttpMethods;

// OPTIONS ~/api/myservice?api-version=[1.0|2.0|3.0]
app.MapMethods("/api/myservice", [Options], ( HttpContext context ) =>
{
    context.Response.Headers.Allow = new( [Get, Post, Options] );
    return Results.Ok();
});

HTTP/2 200
allow: GET, POST, OPTIONS
api-supported-versions: 1.0, 2.0, 3.0

using static Microsoft.AspNetCore.Http.HttpMethods;

// OPTIONS ~/api/myservice?api-version=[1.0|2.0|3.0]
[HttpOptions]
public IActionResult Options()
{
    Response.Headers.Allow = new( [Get, Post, Options] );
    return Ok();
}

HTTP/2 200
allow: GET, POST, OPTIONS
api-supported-versions: 1.0, 2.0, 3.0

// OPTIONS ~/api/myservice?api-version=[1.0|2.0|3.0]
[HttpOptions]
public IHttpActionResult Options()
{
    var response = new HttpResponseMessage( HttpStatusCode.OK );
    response.Content = new StringContent( string.Empty );
    response.Content.Headers.Add( "Allow", new[] { "GET", "POST", "OPTIONS" } );
    response.Content.Headers.ContentType = null;
    return ResponseMessage( response );
}

HTTP/1.1 200 OK
allow: GET, POST, OPTIONS
api-supported-versions: 1.0, 2.0, 3.0