DEV Community

Jonas Samuelsson
Jonas Samuelsson

Posted on • Edited on

3 1

Http endpoint versioning

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();
}
Enter fullscreen mode Exit fullscreen mode

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()
   {
      ...
   }
}
Enter fullscreen mode Exit fullscreen mode

Do your career a big favor. Join DEV. (The website you're on right now)

It takes one minute, it's free, and is worth it for your career.

Get started

Community matters

Top comments (1)

Collapse
 
berkangayterminal profile image
CodeNinja

👍👍

👋 Kindness is contagious

Immerse yourself in a wealth of knowledge with this piece, supported by the inclusive DEV Community—every developer, no matter where they are in their journey, is invited to contribute to our collective wisdom.

A simple “thank you” goes a long way—express your gratitude below in the comments!

Gathering insights enriches our journey on DEV and fortifies our community ties. Did you find this article valuable? Taking a moment to thank the author can have a significant impact.

Okay