Implementing Modern API Versioning in .NET

Hello everybody I'm Nick and in this video I will show you how you can implement modern API versioning in .NET using the latest tooling available. In this video we will focus on Minimal APIs since this is the new feature added in .NET 6, but this approach can be used for Web APIs as well.

Don't forget to comment, like and subscribe :)

Social Media:

#csharp #dotnet

[LachlanWood-gyut]

Thanks for another great video Nick!

I've recently implemented versioning on an existing API and utilised the mentioned package in this video. I wanted to share my experience here to help others if they are in the same situation.

The situation is that when we developed our APIs, we made a decision to not utilise the `[ApiController]` attribute on our endpoints so that we could gain complete control over how we validate the models and form our responses. If you are in a similar situation and follow all the recommended steps when configuring this versioning package, it will not behave as expected. After a few hours of fiddling, reading through a bit of documentation and class annotations, I found that in the options there is the `options.UseApiBehavior` which you can set to false to include the controllers that don't have the `ApiController` attribute.

[raptorjesus]

We literally do not use the API version concept at service level, instead we run the service multiple times with different versions. The proxy handles the /api/v1 and /api/v2 portion of the url.
Once a new API version is introduced the branches for other API versions are maintenance only.
Moving the API version concept to service level is just cluttering already dense api controllers up even more.

I personally advice handling API versions in NGINX/Apache.

[arithex]

How it started: just make a "/v2/foo" endpoint
How it's going: add dozen lines of boilerplate, dependency injection and a new 3p package dependency

why do we keep doing this to ourselves? is nothing allowed to be simple?

[mihaimyh]

Hi Nick, a video an assembly versioning will be nice.

[wiking]

I like your videos, sometimes you touch interesting for me tasks. You are the one of youtubers that I must watch in slow motion btw ;)

[lexer_]

I have a question about this which actually also applies to many of your other videos. This seems like it is needlessly complicated. Your initial example without any library was orders of magnitudes easier to understand and also just outright much less code. The depth of knowledge of the library needed is arguably much more than just coding the operations you need by hand.
There are examples like mediatr that legitimately seem like they would simplify the core problem. It does a lot more more work for the library consumer than it creates in implementing it.
But this seems like it is a needlessly complex abstraction for a very simple problem. The only good argument in favor of libraries like those is that the user is less likely to implement API versioning in a horrible way. But in my experience this goal of preventing bad programmers from writing bad code by getting them to use good libraries never works. Bad programmers will find ways of using good libraries in the most horrific ways anyway so you really incur the cost of both, the bad programmer and the additional complexity of the library. In my opinion the far better solution instead of implementing these libraries is to just spend the time to properly train your developers in fundamentals and give them the time they need to really grasp the concepts properly and to then let go the people that just don't have the mindspace or interest to learn.

I am of course wording this point more sharply and one-sided than I really see it. There is a lot of grey area here of course. But I would love to see you address this kind of somewhat one-sided critical view of these types of libraries and I feel like everyone could profit if you could make good points in favor of using them.

[andriisnihyr]

So cool, thanks for sharing! I didn't know this package exists.

[paulpeeters]

How should one implement a V2 API that uses most or many of the V1 endpoints except some additional and/or some modified for the V2 version? And the same when other versions are created. We want the consumer of the API to specify either V1, V2, V3 for all of the API endpoints he will be using.

[matthewhamby]

What is the link for the documentation to the swagger classes?

[pbreslinltd]

Awesome video... How do you handle sub versions, minor and patch... I would want to track all changes that are non-breaking as minor and patch changes and have an endpoint call to the complete version which would return V1.15.2 but when they use the API on all the other endpoints, and I use the "v{version:apiversion}" in the URL segment, it should only care about the major...

[Goose-jfcl]

Great video, quick and very informative.

[florianliefers]

With your talking speed you could read out your patreons at the end in realtime 😅. Nice video 👍🏻!

[dputra]

They need to mark the old packages as deprecated. I wasn't aware of the name change to Asp.Versioning for a long time until I found an article written about it.

[JtendraShahani]

Can someone please point me to the article Nick is referring. Don't know how to implement both ConfigureSwaggerOptions & SwaggerDefaultValues.

[brunocandia]

Hi Nick, nice video. This packages also applies to an Http triggered Azure Function? As far as I know the package that is used when dealing with an azure function is not that flexible. For example the Swagger UI generated does not contain a drop-down list to be able to filter by the different versions.

[carstenberggreen]

Awesome overview, efficient and useful!

[jcampos]

I'd love to find any tutorials/blog posts or any guidance about how to organize your code (different versions of same APIs, different DTOs, etc.) when doing versioning. I've been using API versioning on .NET for a long time, but I can't find any good "code organization" for it, specially if you don't just want to have full copies of the API (when nothing hasn't been modified) on different namespaces

[Karan-urym]

Is there a way to find out differences or compare the 2 versions. For example if client is using version1 and wants to use version2 but not sure what differences are there. Is there a way to see what changed between version1 vs version2

[ivanomatrisciano]

How would you handle translations in a front-end?

[bakkupavan]

Hi Nick, great video but I am getting an error at app.DescribeApiVersions() IApplicationBuilder does not contain a definition for DescribeApiVersions. Please help.