Version-Neutral

All services should be explicitly versioned. In rare cases, however, you may have a service that is version-neutral. A common scenario is a health check service that behaves in the exact same way, regardless of API version. This might also apply to a legacy service that doesn’t support API versioning. To effectively opt out individual services from API versioning, a service must indicate that it is version-neutral.

Technically, it’s not a supported scenario to completely opt out of API versioning. A version-neutral service has the following characteristics:

• Accepts any valid API version
• Accepts no API version at all (e.g. unspecified)

This is an important distinction and why the term version-neutral is used. A version-neutral service accepts any and all versions, including none. This behavior can be used to define a service that accepts all API versions or service that simply does not care about specific API versions.

It is not possible to have some versions of a controller that are API version-neutral and other versions of the same controller require an explicit API version. If the route of an API version-neutral service matches any other service, it will result in an ambiguous match (e.g. server error).

Web API

[ApiVersionNeutral]
[RoutePrefix( "api/health" )]
public class HealthController : ApiController
{
    [HttpGet]
    [Route( "ping" )]
    public IHttpActionResult Ping() => Ok();
}

A version-neutral controller using the query string method will not require that a client specify an API version. A version-neutral controller using the URL path method will match any well-formed API version in the URL path segment.

Web API

[ApiVersionNeutral]
[RoutePrefix( "api/v{version:apiVersion}/health" )]
public class HealthController : ApiController
{
    [HttpGet]
    [Route( "ping" )]
    public IHttpActionResult Ping() => Ok();
}