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
• Conventions
• ErrorResponses
• RouteConstraintName

ASP.NET Core Specific Options

• RegisterMiddleware
• UseApiBehavior

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(
    options => options.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( options => options.ReportApiVersions = true );

Conventions

This option allows you to construct API version conventions for each of your services as opposed to using .NET attributes. You can also choose to additionally use .NET attributes and the union of both sets of defined API version information will be applied. The default convention builders can be extended and/or replaced in this option. For more information on using conventions see the API version conventions topic.

Route Constraint Name

This option allows you to change the name of the API version route constraint. The default name is apiVersion.

This option is available in 3.0+

ASP.NET Core Specific Options

Register Middleware

This option controls whether API versioning automatically registers the necessary middleware in the ASP.NET Core pipeline. The default value is true. By setting this property to false, you must also invoke app.UseApiVersioning() in the Startup.Configure method. This option is meant for advanced scenarios where you need full control over when middleware is registered and the order in which it is executed in.

This option is available in ASP.NET Core 3.0+

Use API Behavior

This options determines whether API behaviors should be observed to filter API controllers. API versioning is meant for APIs so there is a common desire to filter versioning to API-specific controllers. When the value is false, no filtering occurs and all controllers are versioned.

This option is available in ASP.NET Core 3.0+

Behavior in 3.0

In 3.0, ApiVersioningOptions.UseApiBehavior was defaulted to false. By setting this value to true, controllers would be filtered to any controller with [ApiController] applied to it. The ApiControllerAttribute was introduced in ASP.NET Core 2.1.

Behavior in 3.1

Starting in 3.1, ApiVersioningOptions.UseApiBehavior defaults to true. API controllers are now identified and filtered according to:

interface IApiControllerSpecification
{
    bool IsSatisifedBy( ControllerModel controller );
}

There are two built-in specifications:

• ApiBehaviorSpecification - matches controllers decorated by [ApiController]
• ODataControllerSpecification - matches controllers decorated by [ODataRouting]

An API controller will be considered any controller that matches at least one specification. If a built-in specification does not meet your specific needs, you can create your own:

// considers controllers inheriting from Controller to be a UI controller
public class NonUIControllerSpecification : IApiControllerSpecification
{
    readonly Type UIControllerType = typeof( Controller ).GetTypeInfo();

    public bool IsSatisfiedBy( ControllerModel controller ) =>
        !UIControllerType.IsAssignableFrom( controller.ControllerType )
}

Register your specification in the services configuration:

services.TryAddEnumerable(
    ServiceDescriptor.Transient<IApiControllerSpecification,
                                NonUIControllerSpecification>() );