In this post I will show you how to versioning you REST APIs, and I will explain to you when to versioning and what is the best approach to apply and implement this feature to your APIs.

First, let us take an example to build our idea based on it.
What are the APIs that I'm working on it. What are the kinds of APIs that I build.
Is itwhether services to show the case of the current Whether orbanking services orAPIs for internal uses by your organization?
If you develop or build APIs for internal uses by your organization DON'T versioning your APIs at all because you have to put in your mind that when you apply the versioning to your APIs, you increase the maintenances process for all versions of your APIs. And you actually build APIs for internal uses( NOT for customers ), or by other way you have not external consumers to use your APIs.

Now let us assume taht we have built anwhether services APIs for external uses by multiple consumers.

The signature of our Controller it would be like so:

[Route("api/whether")][ApiController]publicclassWhetherController:ControllerBase{[HttpGet("ShowCuurentStatus")]publicstringShowCuurentStatus(){stringresult="The current status  of the weather is: 35";returnresult;}}

We have an endpoint that return the current status of the whether, and for demo purpose I returned a hard code result like so:

Thecurrentstatusoftheweatheris:35

Let us say we have more than one hundred (100) of consumers uses our APIs. And our endpoint works perfectly with them.And after long time we decide as the owner of this API to improve the result of theShowCuurentStatus( )Action Method. And we decide to include theAir Quality to the result depend on the current status of the weather. for instance, the result it will become like so:

Thecurrentstatusoftheweatheris:35.TheAirQualityis:Poor

So, when we decide this change, we put in mind that, we need to apply this change without breaking the old result. How we can do that.
We can use the REST APIs visioning.
First, we have to install a NuGet packages:

Microsoft.AspNetCore.Mvc.VersioningMicrosoft.AspNetCore.Mvc.Versioning.ApiExplorer

What is the best approach to versioning you APIs?

To version your REST APIs you have more than one way to let your consumers to get the result from that endpoint depend on specific version.

*You can apply the versioning in query string parameter:
*

api/whether/ShowCuurentStatus?api-version=1.0

Or by applying it inRequest-Header

Or byAccept Header like so:

GET /api/whether/ShowCuurentStatusAccept: application/json;api-version=1.0

Also, you can apply the versioning byURL Path approach,

/api/v1/whether/ShowCuurentStatus

The best approach to versioning you APIs isRequest-Header, and the Request-Header like a meta data for your endpoint.

Now let us see how we can implement this on ASP.NET Core 6

In the program.cs class add these lines of code:

builder.Services.AddVersionedApiExplorer();builder.Services.AddApiVersioning(config=>{config.DefaultApiVersion=newMicrosoft.AspNetCore.Mvc.ApiVersion(1,0);config.AssumeDefaultVersionWhenUnspecified=true;// To Ignore 404 Errorconfig.ReportApiVersions=true;// To show Which Version the Reauest Supportedconfig.ApiVersionReader=newHeaderApiVersionReader("api-version");});

In theAddApiVersioning( ) method we configure it to accept by default theversion 1.0 for all endpoints in our APIs, and this means that, if the consumer forgets to add the version of the endpoint to the header the result will directly match and return the version 1.0 for requested endpoint.

config.DefaultApiVersion=newMicrosoft.AspNetCore.Mvc.ApiVersion(1,0);config.AssumeDefaultVersionWhenUnspecified=true;

In the configuration of theAddApiVersioning( ) I enforce theHeader to be the approach that it should be used by consumers when requesting my endpoints by applying this line of code:

config.ApiVersionReader=newHeaderApiVersionReader("api-version");

TheHeaderApiVersionReader objcet accept a string of array to name your version.

Letter I will show you how to combine more than one approach to get the result by different ways.

Let us jump to ourWhetherController and apply the versiontwo of theShowCuurentStatus( )Action Method:

[HttpGet("ShowCuurentStatus")][ApiVersion("1.0")]publicstringShowCuurentStatus(){stringresult="The current status of the weather is: 35";returnresult;}[HttpGet("ShowCuurentStatusV2")][ApiVersion("2.0")]publicstringShowCuurentStatusV2(){stringresult="The current status of the weather is: 35  The Air Quality is: Poor";returnresult;}

Now if you see the result of theversion 2 of our method it returns a totally different result like so:

Thecurrentstatusoftheweatheris:35.TheAirQualityis:Poor

Let us give it a try by running the application and test it by Postman

In the next image if you see, I make a request to theShowCuurentStatus( ) endpoint without mentioning any version, and the result coming by default from version 1.0

Second let us make a request toversion two of theShowCuurentStatusV2( ) endpoint without applying the version of the endpoint in the header, and as you can see the result is400 bad request

This error is coming here because I decorate theShowCuurentStatusV2( )Action Methos to accept version 2.0 only.
Let us add theversion 2.0 to the header of the request, and now here we go:

Look carefully at the header of the request, I added a new header to request, and the name of that new header is:

api-version: 2

The 2 here is the number of the version.

How to use multiple approach to accept the version of your endpoints

If I want to give my customers more than one way to apply the version of my endpoint to fetch the current status of the whether instead of the Request-Header only, I can do that by this way:

config.ApiVersionReader=ApiVersionReader.Combine(newHeaderApiVersionReader("api-version"),newQueryStringApiVersionReader("api-V"));

Here I combined two Api version reader to request the endpoints by usingCombine method of theApiVersionReader object.

Also, I can let my consumers to know when I decide to deprecate anyone of my endpoints and that by adding a second parameter to theApiVersion attribute like so:

[HttpGet("ShowCuurentStatus")]**[ApiVersion("1.0",Deprecated=true)]**publicstringShowCuurentStatus(){stringresult="The current status of the weather is: 35";returnresult;}

And here theversion one of theShowCuurentStatus( )Action Methos now is deprecated, if you give it a try you will see the result like soLook to next image:
Look at theapi-deprecated-versions header at the end of theHeaders tap of the result.

And that all I have to show you how to versioning your REST APIs in ASP.NET Core 6.
Thanks for reading.