A scratch guide to API versioning in ASP.NET Core



If I call an API with a URL of https://mybandapi.com/api/bands/4, I’ll get the following response:

{
   "id": 4,
   "name": "The Eagles, man"
}

Now, let’s say I decide to update my API schema with a new field, YearFounded. Here’s how the new response looks now:

{
   "id": 4,
   "name": "The Eagles, man",
   "YearFounded": 1971
}

With this new field, existing clients still work. It’s a non-breaking change, as existing apps can happily ignore it. You should document the new field in The Long Run, for sure, but it isn’t a huge deal at the end of the day.


Let’s say you want the name to be instead a collection of names associated with the band, like this:

{
   "id": 4,
   "names": 
   [
     "The Eagles, man",
     "The Eagles"
   ],
   "FoundedYear": 1971
}

You introduced a breaking change. Your consumers expected the name field to be a string value, and now you’re returning a collection of strings. As a result, when consumers call the API, their applications will not work as intended, and your users are not going to Take It Easy.


Whether it’s a small non-breaking change or one that breaks things, your consumers need to know what to expect. To help manage your evolving APIs, you’ll need an API versioning strategy.


Since ASP.NET Core 3.1, Microsoft has provided libraries to help with API versioning. They provide a simple and powerful way to add versioning semantics to your REST services and is also compliant with the Microsoft REST Guidelines.


In this post, I’ll show you how you can use the Microsoft.AspNetCore.Mvc.Versioning NuGet package to apply API versioning to ASP.NET Core REST web APIs.