Asp.Net Core 5 - Rest API Versioning

hello friends thank you for watching this video i am muhammad and today we are going to be discussing and implementing api versioning in asp.net core 5. so what are we going to be covering today first we're going to be discussing what is the problem and then we're going to be discussing what is versioning how can we implement it the different types of versioning that we have the ingredients that we're gonna be needing and then we're gonna actually start coding as always you will find the source code in the description down below please like share and subscribe if you like this video it will really help the channel so let's get started so what is the problem that we're facing so basically how are we going to be dealing with changes over time that's going to be the main thing that we're going to be tackling so once we once we build our application and we deploy it and the users and the system start to integrate with it it's impossible for us to change any implementation from that api because any changes that we do is basically we're gonna be breaking those user and system integration and we don't really want to do that second is with time requirements will change so we might need to add new functionalities we might need to add some bug fixes we might need to remove some implementation and any of those requirements that we're going to be adding might break the current version of our app of our api and we don't really want to do that we need to figure out a way where we are going to be able to add those new functionality and new requirement without actually breaking the existing one and at the end of the day updating our api is a very complex problem because basically we need to maintain the current implementation as well as adding new functionality and there's going to be different ways for us to implement this some people will have two different apis on two different services two different servers and this is gonna be causing headache because the more versions that you're gonna be having the more servers that you need and it's gonna be more harder to manage but for this reason we have something called api versioning so basically api versioning is evolving the api without breaking the clients who are currently using it so it means that we can add more functionality we can add all of those new requirements that we want to add we can fix all of the fixes that we want to do and actually and implement it and push it to production without actually breaking any of the current implementation that our customer might be using api versioning is not product versioning basically api versioning focus on more of the functionality and the work behind rather than the actual product versioning api versioning is complex since we need to support old and new version we need to make sure that the changes that we make does not really break the existing functionality we could have a new client that we want to use the latest and greatest functionality while we have other clients who wants to use the basic functionality that we support and we need to be able to maintain these two running simultaneously so this is why api versioning is really important when it comes to api versioning there is no one size fits all there's no one right implementation you need to take about you need to think about how what is the use case that you have what is the best approach that suits the api that you currently have i cannot tell you or use this on top of that it need you need to see what type of user case scenario that you have what type of api that you have how the actually the users are using it and based on that you need to make that decision okay based on that i need to use this types of implementation as well as because there's a lot of ways we can implement api versioning and there's no right answer for all every case is different and based on your user scenario you need to decide as always we need to think about our clients and how they are using our api basically we need to achieve client satisfaction as much as we can because the easier for them to upgrade from one version of the api to another the more successful our buyer is going to be and we're gonna make it as easy as possible for them even though it's gonna it might be a bit harder for us to implement it so what are the different types of api versioning that we have we're gonna be discussing four types of api versioning query string uri versioning metadata and meta queries or media types and headers so what is query string versioning as we can see from the first picture here at the end of the url we have a query string with api dash version equal one so basically we are specifying a version of our api into the query string and we're telling it which version of api we're going to be using the other one is we are actually specifying the number inside the url so api for the slash 2.0 for example which means that we are referring to the second version of our api and this uh this is also a url based versioning so the first one is the query string where we are appending a query string and the other one is we're actually adding a the version number to our main url the the third and the fourth version of api version are based on header versioning and media type versioning so basically the first one is we're going to be able to send a custom header with the version number of the api which we're going to which we want to use and the second one basically is we add some information to the accept type where we specify the version number that the api we want basically we specify the version number of the api we want through the accept through appending the accept header so what's the ingredients that we're going to be needing in order for us to build our application basically we're going to be needing three things we're going to be needing our ide which is going to be the visual studio code second we're going to be needing the nut 5 sdk as well as postman in order for us to test our api you can find the links you can download all of these through the links on the screen or you can find them in the description down below now let's start coding after we have downloaded all of our ingredients now it's time for us to start developing the first thing we're going to be doing is we're going to be checking that the sdk has been installed successfully on our machine in order for us to do that we're going to be utilizing the version keyword so not dot nut dash dash version and as we can see here we have version 5.0.202 which is the latest version by the time of this recording if you see any other number that should be fine if you see any error what you need to do is you need to redownload the dotnet sdk and reinstall it again next basically right now we're going to be creating our new application so in order for us to do that we're going to be utilizing the not the new keyword so not new web api dash on and we're gonna call it sample api great so this should take few seconds to complete perfect now this is is created let's open it up in visual studio code perfect so once we have done that let's open the terminal and let us just build our application to make sure that everything is building as it should be so dotnet build and as we can see build succeeded perfect so the next step is we're gonna be cleaning up this project so we're gonna be dating two things first we're gonna be dating the weather forecast.cs and then we're gonna be deleting the controllers great so once we have done that the next step for us is we need to create a new file inside our directory root directory and this folder it's going to be called models great once we have created this folder we need to create a class inside this folder and we we're going to call it user and this user class is going to be representing the model that we're going to be using inside our api so this model is going to have two properties the first one is going to be the id so prop and of type id and the other property is going to be name of type string so prop string of type name perfect now that we have created our model the next step for us is going to be creating our new controller so in the controller folder we create a new class and we're going to call this class users controller great now that we have our class ready let us start by adding some attributes to this class first we're going to be adding the api controller attribute and then we're going to be defining that route for this controller so route api for the slash users great and the next step basically we're going to be inheriting the controller base perfect and right now we're going to be only implementing one action and this action is going to be returning for us a list of users so http gut and it's going to be let's put that parentheses and we're gonna make it public it's gonna turn on i action result and we're gonna call it all users and right now we're gonna be mimicking going to the database and getting the information so we're making db operation and right now basically we're going to create a static list of users and we're going to be returning it so let's user i'm gonna call it users equal new list of user let us fix these references great now we're going to be creating three users so new user and we're given the id equal to 1 and name is going to be muhammad and then another new user and the id equal to and the name we're gonna be giving it as donald duck and the last one is new user and it's gonna have an idea of three and name equal nil great so we have now three users and what we're gonna be doing right now is we're gonna be returning these users back to the user so how are we gonna doing that so we're gonna put return okay and we're gonna send the list of users back perfect so the next step after we have done this is let us test it so first let us build our apis.not build [Music] great now let us run it dot not run now it's running great now let us open postman and as you can see i have already populated it before so let us just do a call to the sport to this url and we can see that we have the response coming back with the three users muhammad and perfect so now we have we are 100 sure that our application is running let us now go back to our ide and let's stop our application now that we have make sure that our api is running as it should be now we need to start thinking about adding versioning to it so how do we do that we're going to be utilizing a package that microsoft provide and we're going to be adding it to our application so to do that we're going to be utilizing the package so dot nut add package it's going to be microsoft dot asp.net core dot mvc dot versioning and this should take a few seconds great once we have it installed let's check our sample api.css approach and we can see that it has been added successfully here great so once we have done that the next step for us to add api versioning is we need to update our startup class so let's go to our startup class and inside our configure services method let's add it here so it's going to be services dot add api versioning so what we are doing here we are just updating let's add a command it's going to be updating the middleware to take to use actually versioning great so right now here once we have added the service that add api versioning we're basically attending asp.net core that it needs to implement versioning perfect so let's see what happened right now if we run our application so let's save this and let us run it apologize let us run it great now let's go to postman again and let us run the application the same request again and we see we have a new error and it says this error that api version is required but it's not specified and this makes it makes sense why because currently we have added uh the line that's basically injecting versioning into our functionality into our application but we still still did not configure it we still did not tell the network how to handle the api versioning so one way of doing it is in order for us to fix this without doing any changes to our code is to append the api version to our url so here if we add a query string we call that api dash version and we give it for example a version of 1.0 and we do the send we can see that the application is running why is that because once we have added the version 1.0 now the asp.net core applications know which version of the api is going to be returning back but you might think to yourself but we didn't specify any version of 1.0 in our application that's correct because once the application has started it had the scan on the controllers and and it saw that there's only one version of the controllers and those uh version of the controllers are basically all wrapped up in a version of 1.0 labels the basic level of the first level of versions that we have so for this reason when we put api version 1.0 it will automatically work so but if we're going to go with this this is still going to be breaking all of our current implementation our users implementation and application implementation because they need to update all of their urls in order for them to add this api version into it so how can we fix that and how can we avoid that so the first thing we're going to be doing is we're going to be going back to visual studio code and basically we need to expand the configuration for ad api versioning so we're going to add options and the first options that we're going to be adding is this line assume default versioning when unspecified which means that in case that we did not specify the api version our url the application automatically will add that version automatically to that url and it's gonna process it so let's see if that will work let us stop our application and run it again now the application is running let's go back to and let's postman the request and now we can see it's working with the api version now let's remove this and less than this and we can see right now it's not working oh sorry i did not save it before running it i apologize so let's run it again and now it should work great so right now we did not specify any api version inside the url but we have it we have got the results back because right now dotnet is currently adding its default version even though we have not specified it in the url if we add it to the url it will still work so let's try it way string api dash version equal 1.0 and we send this request and you can see the information are coming back as it should be great so let us stop the application and let's see what other configuration we can add here so the other configuration that we want to add is the api version so options the default api version so this is the default version that we are supporting so right now because we don't have any uh at the implementation we're going to be utilizing the api version of default so basically if we hover on top of default we can see that it's always going to be the 1.0 because it's a default version that we have if we want to specify our own version it's going to be something like this new api version for example 1.1 and basically this here we are specifying our own api version so let's see how this gonna work so let's run this application dot not run and let's go back to postman and let's do this request again and right now because we have added 1.1 if we change this to 1.1 it will work because we have updated the api version from 1.0 here to 1.1 and if we look at the response header we can see that nothing nothing is really being sent back because we have automatically specified it here but if we remove this and we use the api default version now let's stop the application on the right again and now let's remove this 1.0 to 1.1 actually let's remove all of this we don't really need it and let's send the request and we can see that we are receiving back the information so basically here we have specified that the default version of the application is going to be 1.0 but once we have for example released version 2. 2.0 or 1.1 or 3.0 we can actually specify the default version here so if there is any request coming in without the right version uh in the query string or in the header or in the url it will automatically pick up this version great so once we have done that the third one we're going to add is we're going to send back all of the available api versions so options report api versions equal true so basically this is going to be returning that's other command this is going to return all available api versions so let's see how it's gonna work let's stop the application and run it again now let's go back to postman understand the request and we can see the information coming back but now if we go to the headers we can see that the api supported version is 1.0 so this way if our clients are trying to integrate and they want to know which is the current implementation what they can do is they can do just one call and they can actually get back that's important version directly back in the headers great so now that we have implemented that it's time to add some new apis so we're going to consider whatever we have right now is version one and we're gonna be basically adding version two and we can see how we can implement different versioning in order to switch between version one and version two so the first thing we're gonna be doing is we're gonna be stopping the application and we're gonna be doing some changes to the user class here we're gonna be gonna call it user version one let's make this bigger and then let's update the old controller so it will be v1 and the changes we're going to be making right now is instead of having the users with an id of end we're going to be returning the users with ideal figured this is a very dumb implementation but this is a good way for us to see what's the difference uh how we can handle these two differences that's going to be coming in and how are we going to be able to switch between two versions of the api one of them is going to be an end the other one is going to be a good perfect so once we have done that the next step for us is let's rename this as well we're going to call it user v1 now let's create a new model and this model is going to be basically user v2 and this is going to represent for example the new breaking change that we're going to have and this class is going to be the same so the first property instead of and it's going to be a good but it's going to be the id great and the next one is going to be as well as string and it's going to be the name great so now that we have version one and version two the next step is uh we wanna actually do the separation here so what we can do is uh and a lot of people do that is they can create a new controller and they can control it for example something like that it's going to be users v2 for example controller and then they're going to be building this controller here and then you go of the information well i don't like this approach it's going to make it a lot cluttery and really hard to manage all of these controls specifically with really big applications so the way i prefer to do it is to separate version one and version two by actually having some folders inside the controllers so let's create a new folder and we'll call it v1 and we create a new folder and we'll call this folder v2 and then what we can do is we can move this to folder v1 and let's update its namespace location to dot v1 great and the first thing we're gonna be doing here is we're gonna be specifying that this controller is belong to the version one of our application so how do we do that it's gonna be very simple basically what we're gonna be doing is we're gonna adding a new attribute and this attribute is very easy it's gonna be api version straight to the point and we're gonna specify which version of our application this is referring to so we're going to saying that this current implementation is going to be of version 1.0 great now let us create a new controller and this new controller we're going to be adding all of the new implementation for user v2 so inside the v2 folder we're going to create a new class and this class is also going to be called users controllers and we're going to do the same thing it's going to be api controller let's fix the references next one is going to be the root it's also going to be api for the slash users and then here we're going to be specifying the version and this here is going to be api version and we're going to be specifying version 2.0 great so once we have done that now let's inherit from the controller base and we can implement the same method so let's copy it and we're gonna be basically just changing this one from version one to version two so instead of me typing it this is saving time and now let's fix those references okay great but now we see we have an error because right now id is not an id isn't good so perfect that's we wanted to see so now right now let's implement it so good and using system dot new governed and basically this here is going to be creating a good every time great so now we have those ready now let's discuss how are we gonna be doing the versioning let us start doing the versioning first by utilizing the query string as we have already discussed before so let us run this application and see what do we have now let's go back to postman and let's see what's going to happen if we run our application directly so let's click on send and as you have so here we haven't really changed anything we just did the same request as before and because we didn't specify any version of our api it automatically could took the version 1.0 and we have returned the list of users which still have an id as an integer great now what happened if we change the version to api dash version equal to 2.0 and let's send it and now as you can see when we have specified the version 2.0 it has automatically routed to the new controller and it has returned an id where the ids are going which is what you want to see perfect so now that we have tested this let's do a quick summary we can see right now that we have two controllers one in version one and one in version two and we have added basically two different implementations both of them are returning the list of users but the list of users one of them has a list of id which is version one as an integer and the second one in version two the id is gonna be a good instead of an end perfect so right now this within this implementation we have implemented the versioning based on query string which is fine the next step we're going to be adding something like this so instead of having it as a query string we want to do it something like 2.0 and we can have the actual version inside the uri instead of having it as a create string so how do we do that also it's very easy let's go back to visual studio code let's stop the application let's stop the application and the first thing we're going to be doing is we're just going to be adjusting the route so inside the route here after the word api forward slash and we're going to be adding this so we're gonna put v which is stand for the version that we want and we're gonna be adding version two points and it's gonna be api version and let's try this out so let us run the application again and now let's go back to postman let's remove this and see what happens with without with the normal scenario perfect we can see that the response back return the version one of our application which is the id and right now if we put forward slash v 2.0 and we send it we can see that we are actually getting the id as good perfect so and let's see if we remove the zero what happens we're also getting the same result which is the id of type code great so now that we have updated the route and we have checked that it's working through the url versioning the next step for us is we're gonna be appending the version that we want into the accept header and we're gonna see how this works so the first thing we're gonna be doing is i'm gonna be commenting this out because i'm going to be posting this to github so you can so you guys can have access to the source code and let's remove all of this and now we have our normal implementation without the url so how do we implement media type versioning let's go back to our startup class and inside our startup class what we need to do here is let's add a command and media type versioning great so how do we add it also very easy it's going to be kind of adding the options and we're going to put the api version reader basically the api version reader is we are specifying what type of type of version that we want to implement and we're going to make it equal to new media type api version reader and let's fix the references perfect and now we need to specify what is the key that we want to add so for now we're just going to specify it as x dash api dash version great so now let's jump back to postman and let's see how we can implement this so let's remove the versioning from the url first great now let's send it to see what's happening perfect now we can see that we are actually getting the response back perfectly now what happened if you want to get version 2 so inside the headers tab we want to add the accept keyword so basically the accept header and we're gonna be specifying that we're gonna be getting back the application.json response because it's a default one and with that we're gonna be requesting the version of our api which is going to be the x dash api dash version equal 2.0 sand is getting i think it's colon 2.0 so it needs to be x dash api dash version equal 2.0 and now we click on send and we can see that we have got the response back and now if i remove this sorry we got the response as good which is version two and if i remove this right now and send it we can see that we're getting back the response at version one and if i add it back in and i send it again we are getting it as good perfect so now that we have added this now let's discuss if you want to for example add our custom header so instead of having it with accept we want to add something like this x dot api dash version for example i want to put here 2.0 so how do we accomplish that it's also very easy let's go back to our visual studio code let's stop the application and here let us add a new one which is going to be new header api version reader and we're going to be specifying the keyword that we want which is going to be x dash api dash version and basically the x api version here that we can see this is going to be the header keyword so what we did here is we added a new header version reader api version reader with the keyword which basically right now asp.net code it's going to be listening to it in order to figure out which version of our application is going to be using so let's save this let us run the application again and let's go back to postman and let us send this request so first of all let us disable these two and see what happens perfect we got version one this was accepted the expected one now let's check this one because we have removed this code it should return also a version one of our application great now let's add this which is api access api this version will specify 2.0 and now we should receive go it perfect so right now we have uh specified two ways of attaching the api versions to the header what happen if you want to attach both of them at the same time so let's say we want to attach we want to make it available to add it to the accept header as well as to the our custom api version so how do we do that also it's very simple so what we need to do is we need to add something called api version reader which is basically the class and we're going to be utilizing that from the class something called combine is we're going to be combining different ways in order for us to accept the header of our a sorry the versions of our api so once we have added this combined thing all we need to do is just add the two uh types of api versioning that we want so we want to accept this one so we'll add it like this so right now this will allow us to have the header one and all we do is add a comma and add the second one which we added before let's delete this and right now our api will support both of them basically it's gonna first support the api header if it doesn't find it there it's going to look into the media type and trying to find it there so this way you are supporting two versions of our api two ways to support versioning into our api so let's stop the application and run it again great now let's go back to postman and let's test it out so let's uncheck this and send it we should receive with an end perfect let's check this we should receive the good great let's check this we should also receive with a good grade and now let's remove this and now let's receive it perfect and now if we click on both at the same time we also receive code perfect so now we have done this right now we have covered the four different ways that we can implement versioning into our api so let's do a quick recap the first one using the query string which is gonna which was like this where we have actually added a new query string and we called it api dash version equal 1.0 for example and then from there we have where 2.0 and we were able to specify which version of the api and then we have used the api url versioning where it was something more like this version 2.0 and we are actually specified it within the url and the third one was actually attaching it to the header you can go with either one of these choices every all of them are supported you need to see what is your business case and what is the best way that you can upgrade your api and without breaking any kind of functionality and based on these decisions you can choose one of these four in order for you to create versioning within our within your api great now that we have two versions let us just see one thing so if you go to the headers right now and if you remember the supported versions from before we can see right now that they have two supported versions which is 1.0 and 2.0 and this is all because of this report api versions and now because we have added that now we can see that we have to and we have for example if we have a v3 we see the 3.0 and and so forth great so now let's stop this application and right now we're going to be discussing one last point is duplication of controllers so what we have done right now is we have created version two of uh our application and basically what we want to do is we wanna a way to tell all of our new clients that we wanna integrate with our api once they see that they have version one and version two that they wanna only use version two not use version one and how do we do that basically what we can do is we can add a deprecated value to our controllers it means when they are doing this call it's going to show them within that that this request is deprecated so deprecated means that it's going to be removed soon and we're not going to be used anymore but this way as well our current clients will know that they need to update their application to the latest version so it's a win-win situation so how do we add the duplicated value so let's go back to version one and within here the api version all we need to do is add a comma and type deprecated if i can type and we're going to make it equal true and let's save this and right now let's just build this application perfect i know let's run it great and now let's go back to postman and let's do this call and first of all let's see the body or we still have specified version two which is fine let's remove these and let's see we're getting back the end which is version one but now let's take a look at the response others what do we see we see something really interesting now we have see that the supported header version is 2.0 which is what we want and we can see that the version one that we are currently using is has been deprecated which is great so that way everyone will know from our clients or the system that they are using that there's a deprecated version so right now if i choose for example version 2 i still got this information just so it will also be known to anyone who's implementing it that there's two different version and you shouldn't use version one you should only use version two because the version one is being deprecated perfect so this is gonna be our video for today let us do a quick summary what we have done is we have discussed different version different types the problems without the problem with api upgrading and then we're going to discuss the solution which is api versioning and then we discuss a different way we can implement api version which is r4 which is going to be the query string the url the media type which is the accept header and the custom header and then from that point forward we have discussed how we can add duplication to our existing controllers thanks a lot for watching please write your question in the description down below and if you have reached this part of the video please type your favorite type of chocolate in the comments down below and i will like it and so i will know that you have watched the complete video thank you very much please share this video if you find it useful and have a great day

Channel: Mohamad Lawand

Views: 2,098

Rating: 4.8974357 out of 5

Keywords: dotnet, c#, beginners, step by step, dotnet 5, .net 5, aspnetcore, aspnet, rest api, API, API versioning

Id: Zvh-tVs50q4

Length: 42min 8sec (2528 seconds)

Published: Thu Apr 22 2021