Lecture thumbnail 0:00 / 0:00 In Swagger, you can enable API versions.
The meaning of API versioning is that
you will be maintaining changes made to the API endpoints transparently with the client.
That means for every noticeable modification made to your API endpoints,
you will release a different version.
And the consumers of your API means the developers of client applications
have choice of requesting a particular version of your API.
For example, let’s say the existing endpoints are assumed to be version number 1.
And in future, if you try to make any kind of noticeable change in your API endpoint,
for example, changing the content type of your request body or response body,
otherwise changing the model structure of your response,
or changing the parameters that are needed to be passed by the client.
For example, the client may need to pass more number of values with the request.
Otherwise, changes to the data types of the request parameters or route parameters,
or enabling more number of constraints,
or any kind of noticeable changes in the request and response
would lead to creating another version.
Means you will maintain both code parallelly.
The older or existing code is maintained as version number 1.
And the modified code of your endpoint is maintained as version number 2.
Being from the client application,
you have a choice of requesting either version number 1 or version 2.
For example, for some reason you want to request version 1,
you will include the same information in the request.
Then the server executes the particular version number 1 controller endpoint only,
not the other one.
So you will get the response of the same.
Similarly, if the same client or different client application
wants to access the second controller,
it can request the version number 2.
So maintaining multiple versions of the same endpoint is called as API versioning.
Let’s see how do you enable and maintain the same in Swagger.
For example, I would like to assume this cities controller as the first version,
version number 1.
But for currently,
the test controller which we have created earlier for a demonstration
is no longer required.
So let me delete the same.
Right-click on test controller,
delete.
Now we have only one controller called cities controller.
And let’s try to divide the same into two versions.
For example, right-click on controllers,
add a new folder.
Folder name is v1 for version 1.
And move this cities controller into that v1 folder.
Drag and drop the same.
It asks for changes to the location.
Click OK.
And to automatically adjust the namespaces with the new location,
click Yes.
So the namespace is automatically changed as controllers.v1.
So this is your cities controller at version 1.
In the similar way,
let us try to create another controller
with the same code or maybe different code
that is version number 2.
So copy this cities controller for now.
Right-click on controllers,
add a new folder.
Folder name is v2.
Now right-click on v2 and paste the same.
Now notice that there are two independent copies
of cities controller file.
So one is version number 1
and other one is version number 2.
So this is the first step.
You have to maintain two individual copies of controllers.
Of course, it is also possible to combine
both version 1 and version 2 endpoints
in the same controller file.
But at some point of time in the future,
it becomes clumsy.
Because you have to independently maintain
get methods for all the versions
and post methods for all the versions like that.
So to avoid clumsiness and confusion,
it is preferred to maintain them independently
in separate files in separate folders like this.
So let’s assume a scenario such that
the version 1 contains the same code
exactly what we have already created.
But the version 2 contains only one endpoint
that is get all cities.
But it is going to return only city names
without city IDs.
Maybe it is the client requirement.
And the version 2 is not going to have
post, put and delete requests.
So let’s adjust the code accordingly.
First of all,
there are no any kind of changes needed
in the version 1 cities controller.
It works as it is.
So keep it as it is.
And now cities controller 2,
I mean version 2.
Here, change the namespace as V2.
And align the code.
Now this is the file in the version number 2.
Of course, we are injecting the DB context
and also having get cities action method.
But all the remaining action methods
is being deleted.
We don’t want them here.
Assume that is the client requirement.
I am not saying that we should not maintain.
But assuming that is our scenario.
You can maintain endpoints independently
in two different versions of the controllers.
OK.
But assume we would like to return only city names.
So we are writing select.
We would like to select only city name.
So the return type would be
string type.
IEnumerable of string type.
That’s fine.
OK.
This is our version 2 cities controller.
And already we had version 1 cities controller.
OK. Coding is completed.
This is the step number 1.
But the step number 2 is
we have to enable API versioning
in the swagger level.
Because the swagger has to recognize
the different versions of endpoints.
So switch to the program.cs file.
After adding these controllers
you can say hey services
add API versioning.
But this method is not by default recognized.
In order to recognize or reference the same
we have to install essential NuGet package.
Now right click on the project
or right click on the dependencies
manage NuGet packages.
This package enables API versioning support
for ASP.NET Core web API controllers.
Install that package.
Select the same version number
as of me.
After that you have to install
the subsequent one too.
Again select the same version
and install.
Because this API explorer provides the metadata
that can be read by the swagger.
Now switch back to your program.cs file.
Now this add versioning method is recognized.
And not only that enough
you need to write some configuration settings for this.
So take a lambda expression with config parameter.
You have to configure the version reader.
So API version reader equal to
that is URL segment API version reader.
This version reader enables ASP.NET Core
to identify the current working version of the API
as per the request URL.
That means it expects the API version number
to be included as a part of the URL.
I mean as a part of the route of API controllers.
To do so what we have to do is
go to the custom controller base class
that we have already created.
This is the route template that is applicable
for all the controllers.
And after this literal text that is API.
Here we are expecting the version number
to be included like this.
For example V1 for version 1.
Or it can be V2 also.
Or 3 or 4 whatever it is.
It can also have a major and minor version number too.
For example 3.6
Here 3 is the major version number.
6 is the minor version number.
In case of just V3
it is assumed to be 3.0 by default.
But how do you mention the same as a parameter?
Here V is the literal text that is constant
and this version number might be changed.
In order to mention the same
let’s define a route parameter called version.
And we have to apply a route constraint
that is API version.
This API version is the predefined route constraint
that is provided by
microsoft.aspnetcore.mvc.versioning
And it represents a version number to be present here.
So this whole parameter totally can represent
the actual value which is given
as a part of the request URL.
For example 1 or 2 whatever it is.
Since we have mentioned the same in the custom controller base
and based on this
the actual controller class is inherited from
so it gets applied to the cities controller automatically.
You need not make any changes in the cities controller.
In the program.cs file
this URL segment API version reader class object is required
in order to let ASP.NET Core
to read the version number from this route parameter.
Means if you don’t do this
I mean if you don’t specify the API version number
ASP.NET Core cannot read that version number
which is the part of the URL.
I think we have enabled API versioning.
Let’s run this application and see the output.
But we are getting a response status 500
which means internal server error.
If you press CTRL-SHIFT-I on the keyboard
and open up your network tab
refresh the page.
When you make a request to swagger.json
for this URL
we are getting 500 internal server error response.
The response tab contains actual error message.
It is saying that
conflicting the method path combination
that is API slash version cities
for multiple get actions
that are present in two different folders
I mean v1 as well as v2.
So expect this error for time being.
We will solve this error in the next lecture.
So presently hold it and ignore it.
Directly on another browser tab
you can enter the URL that is
localhost 7 2 2 1 slash API slash
the actual version number that you want to request.
For example, I would like to execute v1
I mean version 1
then cities
So we are requesting the version 1 cities controller.
Of course, we have to include HTTPS also
as a part of the URL.
So you have to add the version number in between
API and cities.
That’s the new change.
So once you enter this particular URL
you are getting a known error here.
That is request matched to multiple endpoints.
So as of now ASP.NET Core still cannot recognize
the difference between cities controller
that is present in two different folders.
That means it cannot be able to identify
which is the which version.
It cannot identify based on the namespace name.
So we have to explicitly specify
that this is the version number 1.
We have to add an attribute called API version.
Currently we are in the v1 cities controller file.
So we have to mention the same as
this is 1.0 version.
You can also include minor version if you want
for example 1.1 or 2 whatever you want.
In real world scenarios
in case if you make any particular changes
then for the modified endpoint only
you will give a different version number.
But for now we can give like 1.0.
Since it is applied on the controller level
it applies on all the action methods
of the same controller.
You can also explicitly mention the API version
for a particular action method.
For example for this second action method
we are writing 1.1 for example.
Okay it is not required for now.
So let it be 1.0 common for all the action methods.
This is for version 1.
Now go to the cities controller file of v2 folder.
But for this we are writing API version.
This is 2.0 in string.
Now ASP.NET Core can identify that
this is version 2 and the other one is version 1.
So it is able to automatically
match the version number value
with actual URL segment.
I mean it can match that version number
with this value.
So try again.
Now enter the same URL.
By the way expect 500 internal server error
for timing for this swagger.
But for now write the same URL
as mentioned before a moment.
HTTP localhost 7221 slash API slash v1
for example cities.
So we are executing the first version
that is it gives the complete information
about cities including city ID and name.
So the return type is IEnumerable of city.
But if you try the same URL with version 2
I mentioned API slash v2.
Now we are executing the second version
of cities controller
which includes only the city names.
Of course there is a city that exists
with empty string value for city name.
Okay ignore it.
So this is the way how do you maintain
multiple versions of the cities controller
endpoints parallelly at the same time
where the client has choice of
requesting either version 1 or version 2
based on their own requirement.
For example let’s say
there is an Angular application
that wants to display both city ID
and city name in a table.
So it requests the version number 1.
But the same Angular application
may be in another page.
It wants to display only city names
in a drop down list maybe.
So it can request the version number 2.
So the client can request
the particular version that it wants exactly.
That is the beauty and purpose
of maintaining multiple versions.
And also if you are maintaining
any official documentation
you can mention the desired
or preferred version number
that can be requested by the clients.
Okay it all happens in real world.
Play Play Play Stop Play Play Start Start Start