Controller Conventions

There are a few implicit conventions to be aware of.

Every Controller Has an API Version

Once you opt into API versioning, every API controller has an API version. This is true even if the controller does not have an explicit attribute or configured convention. When otherwise unspecified, the version applied to a controller derives from ApiVersioningOptions.DefaultApiVersion.

Naming

ASP.NET provides a built-in convention for controller names that use the form [name]Controller where Controller will be trimmed off when exactly that text. API Versioning slightly expands this convention. It will honor the convention of [name][#]Controller. This allows you to have two controller types in the same namespace for different API versions, but for the same resource; for example, ValuesController and Values2Controller will both have the name Values. Naming is important for grouping controllers together.

Alternate grouping, such as by route template, is unreliable. For example, the template api/values/{id} and api/values/{id:int} are semantically equivalent. Understanding that two URLs are not identical, but are semantically equivalent can be complex and requires template parsing to understand them.

.NET only allows a single, unique type name per namespace. You can use the same name by splitting your controllers into different namespaces. You can also explicitly define the controller name using the ControllerNameAttribute (ex: [ControllerName("Values")]).