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.

Although the IApiVersionSelector can be used for other scenarios, it is currently only utilized when no API version is requested by a client and the server allows this behavior. The selector provides the rules that select the most appropriate API version according to the server. There is no built-in capability to ignore an API version explicitly requested by a client.

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

ASP.NET Web API

public interface IApiVersionSelector
{
    ApiVersion SelectVersion( HttpRequestMessage request, ApiVersionModel model );
}

ASP.NET Core

public interface IApiVersionSelector
{
    ApiVersion? SelectVersion( HttpRequest request, ApiVersionModel model );
}

Default API Version Selector

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

Constant API Version Selector

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

services.AddApiVersioning(
    options => options.ApiVersionSelector =
        new ConstantApiVersionSelector(
            new ApiVersion( new( 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(
    options => options.ApiVersionSelector =
        new CurrentImplementationApiVersionSelector( options ) );

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(
    options => options.ApiVersionSelector =
        new LowestImplementedApiVersionSelector( options ) );