API Versioning Options

The ApiVersioningOptions class allows you to configure, customize, and extend the default behaviors when you add API versioning to your application. The configuration options are specified by providing a callback to the AddApiVersioning method.

services.AddApiVersioning( options => { /* configure options */ } );

The ApiVersioningOptions class has the following configuration settings:

• ApiVersionReader
• ApiVersionSelector
• DefaultApiVersion
• AssumeDefaultVersionWhenUnspecified
• ReportApiVersions

API Version Reader

The IApiVersionReader interface defines the behavior of how an API version is read in its raw, unparsed form from the current HTTP request. There are three methods for reading an API version provided out-of-the-box or you can implement your own. The default, configured API version reader is an instance of the QueryStringApiVersionReader class.

Query String API Version Reader

The QueryStringApiVersionReader reads the requested API version from the requested query string. The default query string parameter name is api-version. The constructor for this class accepts the name of a query string parameter so that an alternate query string parameter can be used.

services.AddApiVersioning(
    o => o.ApiVersionReader =
        new QueryStringApiVersionReader( "version" ) );

Header API Version Reader

The HeaderApiVersionReader reads the requested API version from a HTTP request header. There is no default or standard HTTP header. You must define which HTTP header name or names contain the API version information. This method of API versioning does not conform to the Microsoft REST Guidelines.

services.AddApiVersioning(
    o => o.ApiVersionReader =
        new HeaderApiVersionReader( "api-version" ) );

Query String or Header API Version Reader

The QueryStringOrHeaderApiVersionReader reads the requested API version from the requested query string or a HTTP header. A value specified in the query string parameter takes prescendence over a HTTP header. This implementation is useful for existring services that support API versioning, but are not compliant with the Microsoft REST Guidelines. The default query string parameter name is api-version. The constructor for this class accepts the name of a query string parameter so that an alternate query string parameter can be used. No HTTP headers are defined by default.

services.AddApiVersioning(
    o => o.ApiVersionReader =
        new QueryStringOrHeaderApiVersionReader()
        {
            Headers = { "x-ms-version" }
        } );

Assume Default Version When Unspecified

This option enables support for clients to make requests with implicit API versioning. This option is disabled by default, which means that all clients must send requests with an explicit API version. Services will respond to client requests that do not specify an API version with either HTTP status code 400 (Bad Request) or HTTP status code 404 (Not Found), depending whether the requested route exists.

This option should only be enabled when supporting legacy services that did not previously support API versioning. Forcing existing clients to specify an explicit API version for an existing service introduces a breaking change. Conceptually, clients in this situation are bound to some API version of a service, but they don't know what it is and never explicit request it.

When this option is enabled, clients will be able to make a request without specifying a specific API version. The API version of the service that is selected will be based on the configured IApiVersionSelector.

Default API Version

This option defines what the default ApiVersion will be for a service without explicit API version information. This is useful for services that use implicit API versioning in their initial release. This value can also be used for services that may be defined in external assemblies that are not decorated with any API version information. The configured, default value is 1.0.

services.AddApiVersioning(
    o => o.DefaultApiVersion =
        new ApiVersion( new DateTime( 2016, 7, 1 ) );

Report API Versions

This option enables sending the api-supported-versions and api-deprecated-versions HTTP header in responses. When this option is enabled, it will add the ReportApiVersionsAttribute as a global action filter to the application configuration. This option is disabled by default.

services.AddApiVersioning( o => o.ReportApiVersions = true );