How to retrieve list of all implemented versions of my api?

Question

I'm using aspnet-api-versioning in my WebApi project and it works fine. Versions are not hardcoded, they are retrieved from the namespaces.

Now I would like to retrieve the list of already implemented versions. I want to create some endpoint (let's call it GetApiVersions) that user could call to retrieve a simple collection of existing api version numbers, e.g. [1, 2, 3].

In the code responsible for selecting a correct api version based on the retrieved request (CurrentImplementationApiVersionSelector, SelectVersion method), there is an ApiVersionModel parameter with the ImplementedApiVersions property.

The ImplementedApiVersions property seems to be exactly what I need, but I have no idea how to access it within my GetApiVersions endpoint. Is there a way to retrieve it? Or is there any other way to programmatically retrieve a list of implemented api versions?

Answer 1

I wasn't able to access ImplementedApiVersions property. I had to come up with a workaround. I've created a service (called ApiVersionService) with a static field (List<string> ApiVersions). Service allows to register and read registered versions. As I'm using swagger, I registered all versions in SwaggerConfig.cs file:

configuration.EnableSwagger(ApiDocConfiguration.RouteTemplate, swagger =>
{
    swagger.MultipleApiVersions(
        (apiDescription, version) => apiDescription.GetGroupName() == version,
        info =>
        {
            foreach (var group in apiExplorer.ApiDescriptions)
            {
                apiVersionService.AddApiVersion(group.Name);
                // some other code
            }
        });
});

Simple endpoint allows me to retrieve all versions:

    [HttpGet]
    [Route("versions")]
    public IHttpActionResult GetVersions()
    {
        // apiVersionService returns the data stored in ApiVersions field
        var versions = apiVersionService.GetApiVersions();
        return Ok(versions);
    }

Answer 2

@Marta what is your goal? What do you expect to do with the API versions once you have them? That will dictate the solution.

If all you want to do is report this information back in requests, this is built-in; you need only turn it on.

options.ReportApiVersions = true;

This will return the api-supported-versions and api-deprecated-versions headers. You can see this and more information in the Version Discovery wiki topic.

You can also use the GetApiVersionModel extension method on the currently executing action in your controller. Again - depending on when and where you are in the pipeline determines how you retrieve the information.

For documentation type scenarios, you want the API Versioning API Explorer package as well. That will provide an IApiExplorer implementation for Web API that will collate all APIs and routes by API version. You can reorder them as desired. This is the same approach/technique that Swagger/OpenAPI generators use to build their documents. You integrate it into your application via:

var apiExplorer = configuration.AddVersionedApiExplorer(options => { });

// TODO: use the API Explorer

Exactly how you use the API Explorer is up to you. Do note that the built-in IApiExplorer interface doesn't support the notion of grouping. If you rely purely on the interface, you'll get a flatten list. This will matter depending on where you reference the API Explorer implementation. If you request the API Explorer later in your application, you either have to work within the confines of the original IApiExplorer interface or cast up to VersionedApiExplorer. The AddVersionedApiExplorer extension method always returns a VersionedApiExplorer. You can also imperatively create and/or extend the VersionedApiExplorer rather than using the provided extension or configuration.Services.GetApiExplorer().

You can see an example of integration here. However, if you really want to see how it's used and you're not familiar with IApiExplorer, then you probably want to look at a repo such as Swashbuckle.

I hope that helps. Feel free to ask more questions.

Answer 3

Use can use the following interface, Microsoft.AspNetCore.Mvc.ApiExplorer.IApiVersionDescriptionProvider and get access to ApiVersionDescriptions

There is list of all implemented versions!