Skip to content

API Versioning Options

Jump to bottom
Chris Martinez edited this page Jul 28, 2016 · 16 revisions

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 ) );

API Version Selector

The IApiVersionSelector interface defines the behavior of how an API version is selected for a given request context. This service is typically only used when a client has not requested an explicit API version and the AssumeDefaultVersionWhenUnspecified option is enabled. The role of the API version selector is to select the appropriate API version given the current request and a model of available API versions.

There are four API version selectors provided out-of-the-box or you can implement your own. The default, configured API version selector is an instance of the DefaultApiVersionReader class.

Default API Version Selector

The DefaultApiVersionReader always selects the configured DefaultApiVersion, regardless of the request or available API version information.

Constant API Version Selector

The ConstantApiVersionReader always selects a user-defined API version, regardless of the request or available API version information.

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

Current Implementation API Selector

The CurrentImplementationApiVersionSelector selects the maximum API version available which does not have a version status. If no match is found, it falls back to the configured DefaultApiVersion. For example, if the versions "1.0", "2.0", and "3.0-Alpha" are available, then "2.0" will be selected because it's the highest, implemented or released API version.

services.AddApiVersioning(
    o => o.ApiVersionSelector =
        new CurrentImplementationApiVersionSelector( o ) );

Lowest Implemented API Selector

The LowestImplementedApiVersionSelector selects the minimum API version available which does not have a version status. If no match is found, it falls back to the configured DefaultApiVersion. For example, if the versions "0.9-Beta", "1.0", "2.0", and "3.0-Alpha" are available, then "1.0" will be selected because it’s the lowest, implemented or released API version. Your services must be decorated with one or more API versions for the selector to work effectively or it will always select the configured DefaultApiVersion.

services.AddApiVersioning(
    o => o.ApiVersionSelector =
        new LowestImplementedApiVersionSelector( o ) );

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 );
Clone this wiki locally