ASP.NET API Versioning for Web API & Minimal API a comprehensive introduction

today I am going to cover how to implement  API versioning for both standard web API and   minimal API why do we need API versioning once  an API is deployed and clients start using the   API the functionality of the API is kinda set  in stone we cannot just go ahead and change the   functionality as the user do not expect any  change to it so API versioning is needed to   support changes to a public facing API and  usually we need to support multiple versions   of the API at the same time my strategy is  to use versioning pattern that is easy for   the clients to accommodate and there are four  main strategies using which we can version a   web API and they are mainly through URL through  query string through header and through content   type and in this video I am going to show all  those four approaches so for the purpose of   this I have added a couple of NuGet package pages  and for the minimal web API versus standard BPI   the NuGet package will be little bit different  so for the standard web API we'll need to add Microsoft.AspNetCore.Mvc.Versioning and  Microsoft.AspNet Core.Mvc.Versioning.Api   Explorer these two new get packages are  needed for standard API and I'm going   to show what is needed for minimal  API once we finish the standard API   so right now for a standard API I have  a standard out-of-box weather controller   which Returns the weather information and what  I am going to do is I am going to implement the   API versioning for this now to start with this  do not need a version but I personally suggest   everyone to start with a version with version 1.0  itself because then it becomes easier to introduce   newer version later because your client already  knows that your APIs are versioned and whatever   strategy you use they'll start using it on day  one so let's configure the API versioning so for   configuring the API versioning here what we are  going to do is we are going to start with the   builder.Services.AddApi.Versioning and that  is the method or the extension method that   we are going to use which is AddApiVersioning  and AddApiVersioning comes up with the Action   using which we are going to configure  how we are going to version the API so first thing what we are going to do is we are  going to provide a default API version for the API   meaning if the customer do not pass the version  through the query string or header or content   type then it is going to pick up the default API  version the URL based API version is going to be   little bit different and it's because the API  version itself is in the URL so if you don't   pass the version you are going to get a 404 that's  why it works little bit differently but for query   string header and content type if the user do not  provide an abortion you ideally want to provide a   default version and that is why I personally  prefer API versioning through query string   header or content type because it becomes much  more easier to support a default version so for   setup the default version what we can do is we can  use this action value and say DefaultApiVersion   and this is going to be new of ApiVersion and we  can give here 1.0 an API version as you can see   can have major and minor version and we are  going to use major version as 1 and minor   version as zero and I am going to just get rid  of this namespace and add it as a using statement so for assuming the default version,  the second thing we need to set up is   setup.AssumeDefaultVersionWhenUnspecified  so if the user do not specify the version   number in query string header or  content type we want to assume the   default version number which we just set  up and we're going to set it up as true   next after we set these two things up we want to  report the API versions to the user so that the   user know how many versions are supported for this  API and for that we can do setup.ReportApiVersions   and we can set it to true and finally what  we can do is we can do setup.ApiVersionReader   and the API version reader is what strategy we  are going to use for API version now here if we   do not specify as you can see the default value  for this instance is QueryStringApiVersionReader   so if we do not specify anything by default it  is going to use the query string so for the time   being we are not going to specify anything  because we want query string to be specified   now let's run this application and once we  run the application we are going to test it   through Postman and if we run we can see we  are getting the data and we are getting the   data because we said we have a default  API and the version is 1.0 now let's go   and get rid of the default API version and also  assume default API version and before I do that   let me also show you that in the header we've  got the API supported versions and is showing   1.0 so in the header response header we can  see or the client can see what are the version   of API that is supported by the API now if I  restart this now if we execute the same method we are getting an error because API version is  unspecified we did not specify any version so   if we need to do that I'll keep this part  of the code AS commented and we'll go into   the API and now in the API we are going  to declare the version number for the API   and for the version number what we can do is  here we can add an attribute called ApiVersion and for the version number we are going to  give 1.0 that's the major and minor and then   what we are going to do is for this method we are  going to say that this method maps to the version so we are going to say this method maps to 1.0  version of the API so now let's run so at this   point we do not have any default version and we  are also not assuming default version if it is   not specified now given that for the API version  reader by default it is query string so what we   can do is we can pass the API version in the query  string so we can do question mark api-version   is equal to 1.0 and try to execute this and  then given that we have specified the version   number in query string we are getting  back the result and it is picking up this method through this mechanism now  let us go back and change this and set   the default and now let's try using the  other types of mechanism so we can use   setup.ApiVersionReader is equal to  new off and we can here we can say HeaderApiVersionReader and I need  to add the namespace here which is   Microsoft.AspNetCore.Mvc.Versioning and here  inside the API version reader I am going to   specify the header and for header I'm going  to use x-version I prefer using x- for custom   header because that is a standard practice  so now we specified that we are going to use   header based strategy for API version so let's  run the program again and then again go to the   postman and we'll try to execute this now this  time we don't want to specify the API version is   query stream instead we can specify it here so we  can add X that version and where we can give 1.0   and run and we'll get this and we'll give a  version which does not exist 1.1 and we can get   the error as this is an unsupported version and  if we go to header which is the response header   in the response header we can see the supported  version as 1.0 as expected and in the body we get   unsupported API version exception now the third  way of doing this is going to be through the media type API version reader and for media type  API version reader here also we have to provide a   parameter name and I'm just going to keep it  as x- portion now once we do the media type   parameter we will need to pass the version number  in the content type header so now if we go here   I'm going to get rid of this  and in content type we can do application Json and after that we can  give x dash version equal to 1.1 first   I will show that it's not working with  1.1 and I'm going to go ahead and execute   and you can see we got version not  supported and then we can change it to 1.0   execute and we'll get the data back so these are  the three ways we can set up versioning now let's   go ahead and create a new version of this method  so that we can show two versions working so we can   go here copy this and paste it again and name it  as get one because we have same method so this is   not going to be supported and I'm going to use  weather forecast one this is a model I created   here which is whether for plus 2 so let me  rename it weather forecast 2 here weather   forecast 2 and weather forecast 2 do not  have any summary so that's the change   I got that and I'm going to set it as 1.1 and here  I'm going to add version 1.1 now I'm going to run   the application and there will be one problem when  we just run the application and the problem is   going to be with swagger so we'll quickly sort the  problem out but first let me show you the problem   you can see Swagger is failing and the reason  is we have two definition for the same method   so to change it I'm going to go into program file   and in the Swagger chain where we have the add  Swagger chain I'm going to add a piece of code   so in the add Swagger gen we can use the  Lambda function here and we can say this to   and it's a c Dot resolve so you see that there  is something called resolve conflict actions   so we can use that and here we can say this Dot  take loss so if there are two you want to pick   up the last one that's all and that's about it  so if we do that the Swagger is going to start   working as expected though we are not going to do  anything with weather but this is just to show if   you have conflicting method we can just use the  last one and it's just going to work so let's go   back here now we have two versions zero and one so  if we run the zero version or 1.0 version we are   going to get the same response as before and then  here we can come in and we can change it to 1.1 and run it again and this time you can see  we are getting a different data structure   from the 1.1 version so this shows how  we can support version in a standard   asp.net core web API using the versioning NuGet  package provided out of box by the.net framework   I have so far shown three ways one is using the  header second is using the content type and third   is using the query string now let's look into  how we can support the same thing using uh URL   so for the URL here for the controller part what  we can do is in the route we can say portion V and for the version number we will say  version colon and we're going to use API   portion so now if we restart the program again  we can go back to postman and this time if we   try to execute we'll get a 404 but here if we  say version 1.0 slash it will start showing up   1.0 version and similarly if we do 1.1 it  is going to show the 1.1 version response   now let's do now next thing what we want to do  is let me first get rid of this I don't prefer   version in the URL now if we want to now  that we have both the version up and running   we want to deprecate the older version so for  that what we can do is we can go here and say deprecated is equal to true and once we do  that what is going to happen is in the HTTP   header it is going to start showing in the  response it is going to start showing that   this particular version has been deprecated  so if we go here and if we get rid of this URL   and enable the content type because that's  what we have configured right now here we   can see that API duplicated versions and it is  showing that version 1.0 is deprecated whereas   the version supported is 1.1 so this gives an  information to the caller that version 1.0 is   now deprecated which is also a very important  feature in my opinion which is supported out   of box and it's so easy just by this mechanism  now other thing if we we want to do is if we do   not want to use these options here we can also  configure these in program itself using another   option and that is using conventions so here  what we can do is we can say so we can set up Dot conventions and then we can basically use  the conventions here so we can say controller   and we can give this controller name  which is weather forecast controller here so we create this let me add the namespace for  the controller and then we can say convention Dot   has API version and here we can say new  APA version 1.0 com dot has API version 1.1 and then we can also have similarly  convention Dot as deprecated version   and we can say 1.0 is deprecated so  we are doing the exact same thing   as here but we we are doing it inside of the  program class or the dependency injection   class now it totally depends on preference for  me I prefer keeping it in the controller class   because it gives little bit better readability  to the developer whoever is going to look into   the code and understand that okay this is what  we are doing rather than keeping everything in   a centralized place now for some people this  might be what they prefer and if we run this   application we are going to see the exact same  behavior as before in terms of we are going to   if we run it we are going to see the exact  same header as well as exact same body here so we see the body and if we go to header we see  the exact same thing now it says supported 1.0   1.1 both and deprecated 1.0 is because we have set  up both as supported if I get rid of this one it's   not going to show this message but this is how we  can do it now let's get into the minimal API and   for minimal API the first thing we want to do is  we want to check what is the nuget package that   we are using and for this one we are using SP dot  versioning.http nuget package and then what we are   going to do is for the purpose of setting it up  we can kind of copy paste part of this code not   everything is going to work but we can we can  add the we can copy this much so we are copying   the Swagger gen because we need to support that  as well as we are copying the API versioning not   the full part is what is going to be needed so  we're going to get rid of the convention part   we're just going to keep this and for the API  version we're just going to add the namespace   asp.warsioning and now we have set it up so this  is the standard thing we are setting up a default   version and we are doing everything that we  did before and we are supporting media now   here we're going to we can support all the four  but and then here we have this weather forecast   so in this application now we want to support  the API versioning so for that what we can do   is we can do dot with API version set but for  this to work we have to declare something called   as a version set so let's declare the version set  here so for that what we can do is we can say bar portion set is equal to app Dot new API version  set and then to this one what we can do we can do   has API version and here we  can say new API version one   zero and then next thing what we can do is we  can just do a build because we are just doing   one when we add two then we'll support two and  here we are going to provide the portion set   here and then we can do same thing we'll have to  map it so we are going to say map to API version   and similarly we say new  API version one comma zero   so at this point this application should work  the same way as the other application so let me   setup is a startup project and let me run this  application now and it's the same weather forecast   so if we run this and try it out in Postman  we should be able to get the version 1.0 and   we should be able to see in the header that  it supports one version so let's quickly run   this application and it is running on a different  port so let me go ahead and change the port here and if I ask for portion 1.1 let's let's start  with version 1.1 and execute that and we can see it doesn't support  version 1.1 and now let's try 1.0 and we can see it is showing up the  1.0 and in header it is showing API   portions is 1.0 now let's go back  quickly and create a second method so we're going to create the second  method name it as weather forecast to   so that we do not have any problem  and it is going to map to version 1.1   and this is going to return where the  forecast to doesn't have a summary weather forecast 2 it doesn't have a summary   and then here we can go and do uh has  API version one comma one and then Dot has deprecated version and for the  duplicated version we are going to   have 1.0 and I'm going to get rid of s  version of 1.1 okay so now if we run this we should see a similar Behavior meaning we should  see supported version as 1.1 deprecated version   is 1.0 and we should be able to access both 1.1  and 1.0 so now let me go ahead and execute this   and you can see supported version  is 1.1 deprecated version is 1.0   we got the value for 1.0 and let me try out 1.1 and we can see we've got the new data  structure for 1.1 so this is all working   as expected so this is how we can Implement  API versioning in both standard API as well   as minimal API using out-of-the-box NuGet  packages if you like this video please give   me a thumbs up if you are new to my channel  and you think you are getting value out of   my Channel please subscribe to my channel  and thanks so much for watching this video

Channel: DotNet Core Central

Views: 3,153

Keywords: api versioning, asp.net api versioning, asp.net core minimal api versioning, minimal api versioning, asp.net core web api versioning, asp.net web api versioning, asp.net core api versioning, web api versioning

Id: XdKpAFy6It8

Length: 25min 1sec (1501 seconds)

Published: Mon Nov 14 2022