Reading ApiVersion with ASP.NET Core Versioning

ASP.NET Core Versioning is the red headed step child of the ASP.NET Core family. Unlike Dependency Injection, Routing, and HealthChecks, Versioning doesn’t have a page on the official ASP.NET MSDN documentation. What makes that odd is that Microsoft has internal REST Versioning Guidelines that they follow (AzureDevOps REST API). And, most API companies strongly suggest using versioning with APIs. But, again, Microsoft doesn’t have a page for it in their official MSDN documentation?

So, what does the ASP.NET Core API Versioning team have in the way of documentation? Their github repository, a good wiki guide, and a set of examples that can help you get started right away.

While the examples can help you get started, it does get a bit tougher when you want to do a little more advanced scenario. Here’s an example:

• Url: https://somesite.company.com/apis/v1/hr/jobs
  
• Optional header: x-comp-api-version: 1.2
  
• In the example, the /v1 part of the url segment indicates the major version of the API to use. And, the API will return the result of the latest minor version implementation of that major version. Optionally, you can override the minor version used with the optional header.

So, the ASP.NET Core Versioning team did setup a way to do a fallback. Where if the url segment didn’t contain the api version, then it could fall back and inspect the headers for an api version. But, they didn’t foresee using one convention to override or refine another convention. But, really, who would pre-plan for that scenario?

What they did do was setup an interface, IApiVersionReader, which you can use to implement your own custom logic.

But, here’s where the real problem comes in. The ASP.NET Core Versioning Team started their work back when ASP.NET was the standard language of the day. So, the .NET Core side feels a lot more like a bolt on for an ASP.NET Versioning system, rather than a subsystem specifically designed to work with the Dependency Injection subsystem of ASP.NET Core.

One of the places where this “after-thought” seems to stick out is when you try to implement an IApiVersionReader in ASP.NET Core. In ASP.NET Core …

• You do not define your IApiVersionReader within the Dependency Injection System
• You do not tell the ApiVersioning system of the type that you would like generated for each request
• Nor do you create a factory
• You do define your IApiVersionReader as a singleton instance within the ApiVersionOptions class
• And, you can only define your ApiVersionOptions class during ConfigureServices with AddApiVersioning, not in the Configure method with UseApiVersioning.

So, what if your IApiVersionReader needs a new instance of another class for each request that’s processed? Well … you can pass an IServiceProvider to your singleton instance at creation time. Just make sure you’ve got everything wired up in your IServiceCollection before creating your provider: