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).

Minimal API

var hello = app.NewVersionedApi();

hello.MapGet( "/api/health/ping", () => Results.Ok() ).IsApiVersionNeutral();

MVC (Core)

[ApiVersionNeutral]
[ApiController]
[Route( "api/[controller]/[action]" )]
public class HealthController : ControllerBase
{
    [HttpGet]
    public IActionResult 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.

Minimal API

var hello = app.NewVersionedApi();

hello.MapGet( "/api/v{version:apiVersion}/health/ping", () => Results.Ok() ).IsApiVersionNeutral();

MVC (Core)

[ApiVersionNeutral]
[ApiController]
[Route( "api/v{version:apiVersion}/[controller]/[action]" )]
public class HealthController : ControllerBase
{
    [HttpGet]
    public IActionResult Ping() => Ok();
}