Version Discovery

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.

Reporting API versions is disabled by default. Service authors can enable this behavior by setting the ApiVersioningOptions.ReportApiVersions to true.

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:

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