AV0016: Do not assume default API version

Cause

A default API version is assumed where none can ever apply.

Rule Description

A default API version is only applied to an endpoint that carries no versioning metadata at all. The setting exists to grandfather the clients of a service that was not versioned before. Declaring any version, even a neutral one, takes an endpoint out of that arrangement, as does a route that can only be reached by naming a version in the URL. Once every endpoint is in one of those states, the setting does nothing.

Consider the following code:

var builder = WebApplication.CreateBuilder( args );

builder.Services.AddApiVersioning(
    options =>
    {
        options.AssumeDefaultVersionWhenUnspecified = true;
    } );

var app = builder.Build();

app.MapGet( "/order", () => Results.Ok() ).HasApiVersion( 1.0 );
app.MapGet( "/customer", () => Results.Ok() ).HasApiVersion( 1.0 );

app.Run();

Every endpoint declares its own version, so there is nothing left for the default to be applied to.

Reading the version from the media type is the exception and is never reported. A client asking for application/json has named no version and never will, whereas every version after the first is asked for as something like application/json; v=2.0. Assuming a default is what keeps the original clients working, however the endpoints are declared.

How to Fix Violations

Remove the assignment.

builder.Services.AddApiVersioning();

When to Suppress Warnings

It is safe to suppress this rule if endpoints that rely on the default are declared outside the compilation, such as in a referenced library. See existing services for when assuming a default is the right arrangement.