Can an API version be supported but not advertised?

[jovinson-ms]

Based off the discussion here it sounds possible - I haven't been able to find a way to not advertise an API version that is added by namespace convention.

The specific use case is to add a preview API version that only a small number of users would be aware of without advertising it in the header.

[commonsensesoftware]

Yes, it's possible. There are a few possible solutions, but the simplest is probably to replace the IReportApiVersions service. The built-in DefaultApiVersionReporter is sealed, but it's still very easy to decorate. You would filter out undesired API versions from the model before they are reported. You can then forward the rest of the logic to the default implementation.

Something like:

sealed class MyApiVersionReporter(ISunsetPolicyManager sunsetPolicyManager) : IReportApiVersions
{
    readonly DefaultApiVersionReporter inner = new(sunsetPolicyManager);

    public ApiVersionMapping Mapping => inner.Mapping;

    public void Report(HttpResponse response, ApiVersionModel apiVersionModel)
    {
        // TODO: apply your filtering
        apiVersionModel = new(
            apiVersionModel.SupportedApiVersions.Where(v => true),
            apiVersionModel.DeprecatedApiVersions.Where(v => true));

        inner.Report(response, apiVersionModel);
    }
}

This would omit API versions you don't want to advertise from being emitted, but it doesn't change any declarations. Routing will continue to as is with your undisclosed versions.

You'd register it with:

services.Add(ServiceDescriptor.Singleton<IReportApiVersions, MyApiVersionReporter>());

[jovinson-ms]

Thanks so much for the detailed explanation and reference implementation! Would this scenario be worth adding to the wiki?