API version conventions allow you to specify API version information for your services without having to use .NET attributes. There are a number of reasons why you might choose this option. The most common reasons are:

• Centralized management and application of all service API versions
• Apply API versions to services defined by controllers in external .NET assemblies
• Dynamically apply API versions from external sources; for example, from configuration

Consider the following controller:

[RoutePrefix("my")]publicclassMyController:ApiController{[Route]publicIHttpActionResultGet()=>Ok();}

[ApiController][Route("[controller]")]publicclassMyController:ControllerBase{[HttpGet]publicIActionResultGet()=>Ok();}

Instead of applying theApiVersionAttribute to the controller, we can instead choose to define a convention in the API versioning options.

configuration.AddApiVersioning( options=>{options.Conventions.Controller<MyController>().HasApiVersion(1.0);});

services.AddApiVersioning().AddMvc( options=>{options.Conventions.Controller<MyController>().HasApiVersion(1.0);});

All of the semantics that can be expressed with .NET attributes can be defined using conventions. Consider what version2.0 of the previous controller with interleaved API versions might look like:

[RoutePrefix("my")]publicclassMyController:ApiController{[Route]publicIHttpActionResultGet()=>Ok();[Route]publicIHttpActionResultGetV2()=>Ok();[Route("{id:int}")]publicIHttpActionResultGetV2(intid)=>Ok();}

[ApiController][Route("[controller]")]publicclassMyController:ControllerBase{[HttpGet]publicIActionResultGet()=>Ok();[HttpGet]publicIActionResultGetV2()=>Ok();[HttpGet("{id:int}")]publicIActionResultGetV2(intid)=>Ok();}

The API version conventions might then be defined as:

options.Conventions.Controller<MyController>().HasDeprecatedApiVersion(1.0).HasApiVersion(2.0).Action( c=>c.GetV2()).MapToApiVersion(2.0).Action( c=>c.GetV2(default)).MapToApiVersion(2.0);

If you use API version conventions and .NET attributes, then the constructedApiVersionModel for the corresponding controller will be an aggregated union of the two sets of information.

You can also define custom conventions via theIControllerConvention interface and add them to the builder:

publicinterfaceIControllerConvention{boolApply(IControllerConventionBuildercontroller,HttpControllerDescriptorcontrollerDescriptor);}

publicinterfaceIControllerConvention{boolApply(IControllerConventionBuildercontroller,ControllerModelcontrollerModel);}

Custom conventions are added to the convention builder through the API versioning options:

options.Conventions.Add(newMyCustomConvention());

This built-in convention allows you to version your controllers by the namespace they reside in when applied.

options.Conventions.Add(newVersionByNamespaceConvention());

The defined namespace name must conform to the API version format so that it can be parsed. The language-neutral syntax in BNF is:

'v' | 'V' : [<year> : ['_'] : <month> : ['_'] : <day>] : [<major['_' : minor]>] : [<status>]

The. character is considered a namespace delimiter in many programming languages. This charactermust be changed to_ so that newly added files have the correct format. In addition, most languages do not allow the name of a namespace to start with a number. Since a leading character is required, the first charactermust bev orV. There is no requirement as to where the API version must appear in the namespace.

By default, API versions derived from a namespace will be consideredsupported. If the controller is decorated with theObsoleteAttribute, then the API version inferred from the containing namespace will be considereddeprecated.

Examples

• Contoso.Api.v1.Controllers → 1.0
• Contoso.Api.v1_1.Controllers → 1.1
• Contoso.Api.v0_9_Beta.Controllers → 0.9-Beta
• Contoso.Api.v20180401.Controllers → 2018-04-01
• Contoso.Api.v2018_04_01.Controllers → 2018-04-01
• Contoso.Api.v2018_04_01_Beta.Controllers → 2018-04-01-Beta
• Contoso.Api.v2018_04_01_1_0_Beta.Controllers → 2018-04-01.1.0-Beta

Contoso└ Api  ├─ v1  │  └ Controllers  ├─ v2  │  └ Controllers  └─ v2_5     └ Controllers

Figure 1: Sample folder layout with numeric API versions

Contoso└ Api  ├─ v2018_07_01  │  └ Controllers  ├─ v2018_08_01  │  └ Controllers  └─ v2018_09_01     └ Controllers

Figure 2: Sample folder layout with date API versions