Http endpoint versioning

#aspnetcore #csharp

Are you are developing web apis but not versioning the endpoints?
You really should!
It provides so much freedom to make changes to the api without the risk of breaking consumers.

I'm a big proponent of versioning each endpoint separately.
Mainly because I think the alternative introduces coupling between otherwise potentially unrelated endpoints.
I don't like if a change to one endpoint forces me to bump the version of another unchanged endpoint.

As a side note but kind of related.
If you want to provide an api client for your api, it should include all versions (not just the latest) of all endpoints.
If I'm consuming v1 of endpoint A and B, both for which v2 is available, and need to start using A v2. I should not be forced to switch to B v2 as well.
That scales really badly and only gets worse the more of an api you use.
Ask me how I know... 🙈

They way we've implemented versioning in the products I work on we are using a package called Handyman.AspNetCore (nuget, github). It integrates with the asp.net core routing system and lets you define multiple versions of the same http method / path but with different versions.
By default it uses a api-version query parameter with a {major}.{minor} format, all of which is configurable.

Its really easy to set up, you just configure the required services in Startup.cs.

public void ConfigureServices(IServiceCollection services)
{
   services.AddApiVersioning();
}

Now all you have to do is to decorate your action methods (or controller class) with the ApiVersion attribute.

[ApiController, Route("api/values")]
public class ValuesController : ControllerBase
{
   [HttpGet, ApiVersion("1.0")]
   public IEnumerable<string> GetValues()
   {
      ...
   }

   [HttpGet, ApiVersion("2.0")]
   public IEnumerable<int> GetValues()
   {
      ...
   }
}