ASP.NET API version ranges

Question

Our product is a client/server app that has multiple versions of the client out in the field but has only one server that runs the latest version to service all API calls. We have/will have hundreds of API endpoints and I'm trying how best to handle versioning. What I'd like to do is be able to avoid the laborious task of applying attributes to every single method, or copy entire controllers every time we make a minor change.

I might be misinterpreting most documents/practices on this, but it seems like every time you bump your API you have to go through and do all that work, which seems inefficient at best.

Instead what I'd like to do is apply an attribute to each endpoint with the version of when it was written, then the client finds the the closest version that is equal to or less than the client version.

For instance, if an endpoint was written at [ApiVersion("1.0")] then that is the attribute it gets. If we had to modify it, I'd copy the method, rename it, apply a RoutePrefix attribute so it gets properly hit and apply a new attribute with the version of our whole API (in this example I put 1.5).

Here is a simple example:

[HttpGet]
[ApiVersion("1.0")]
[Route("GetHeartBeat")]
public bool GetHeartBeat()
{
    return true;
}

[HttpGet]
[ApiVersion("1.5")]
[Route("GetHeartBeat")]
public bool GetHeartBeat2()
{
    return false;
}

This works no problem when I use url versioning:

• /api/v1.0/GetHeartBeat or
• /api/v1.5/GetHeartBeat

but /api/v1.3/GetHeartBeat does not since that version doesn't exist..

What I want to happen is if I have a client that is running 1.3, then it will find the closest version that is equal to or less than the latest version. So /api/v1.3/GetHeartBeat would get received, since 1.3 doesn't exist, then it'll look at the closest/earlier version, in this case would be 1.0.

I can write a bunch of route logic to accomplish this, but I feel like there has to be a solution out of the box as I can't be the first person to try this. Is there a nuget package that would accomplish this?

Answer 1

You're really asking two questions. How you map things on the server-side is an implementation detail and there are many options. Attributes are not a hard requirement to apply API Versioning metadata. You can use conventions, including your own conventions. API versions must be discrete. That is by design. An API version is much more like a media type. You cannot arbitrarily add a media type, nor an API version, and necessarily expect a client to understand it.

Since you own both sides, you have some great avenues to make things work the way you want. The server should never assume what the client wants and the client should always have to explicitly ask the server what it wants. The easiest way to achieve your goal is to negotiate the API version. Ok, great. How?

I suspect not a lot of people are doing this today, but API Versioning baked in the necessary mechanics to achieve this very early on. There are many use cases, but the most common are for tooling (ex: client code generation) and client version negotiation. The first step is to enable reporting API versions:

services.AddApiVersioning(options => options.ReportApiVersions = true);

You can also apply [ReportApiVersions] on specific controller actions

This will enable reporting the available API versions via the api-supported-versions and api-deprecated-versions HTTP headers. Remember that deprecated doesn't mean that it doesn't exist, it just means that it will be going away at some point; you control the policy. This information can be used by your client to log warnings about out-of-date versions or it can influence your client's decision in selecting an appropriate version.

Part of your challenge is versioning by URL segment. Yes, it's very popular, but it violates the Uniform Interface constraint. v1.api.com is an endpoint. v1.0/GetHeartBeat and v1.5/GetHeartBeat are identifiers. The two identified resources are almost certainly not different resources, but have different representations. Why does that matter? Changing the identifier (e.g. URL) for every version results in a moving target for the client. Every other method of versioning would use always use GetHeartBeat. I'm sure you're far too down the road to make a change, but this leads into the solution.

It doesn't really matter which controller implementation you use, but you essentially need an action that does something like this:

[ApiController]
[Route("api/[controller]")]
public class GetHeartBeatController : ControllerBase
{
    [ReportApiVersions] // ← instead of ApiVersioningOptions.ReportApiVersions = true
    [ApiVersionNeutral] // ← allow any and all versions, including none at all
    [HttpOptions]
    public IActionResult Options()
    {
        // Allow is required by spec; you may need addition information
        Response.Headers.Add("Allow", new StringValues(new[]{"GET", "OPTIONS"}));
        Response.GetTypedHeaders().CacheControl = new()
        {
            MaxAge = TimeSpan.FromDays(1d),
        };
        return Ok();
    }
}

Now, if your client sends:

OPTIONS api/getheartbeat HTTP/2
Host: localhost

You'll get back something like:

HTTP/2 200 OK
Cache-Control: max-age=86400
Api-Supported-Versions: 1.0, 1.5

If your client is running 1.3, it now has the knowledge necessary to select 1.0 from the list as the most appropriate API version. The Cache-Control header can be used as a way for the server to tell the client how long it can cache the result (but it doesn't have to). I presume API versions wouldn't change more often then once per day, so this seems like a reasonable approach.

You didn't mention what type of client you have. If it's a browser-based client, you may have to do some additional work with this setup to make it play nice with CORS, if it's even required. Alternatively, you could achieve the same result by using the HEAD method. I'd argue that OPTIONS is more appropriate, but you might not find it worth the work to make it play with CORS should you run into any complications.