Instructor: So how do we add versioning in the API?
So the version can come in three forms in the API.
The first one is in the URL itself, something like this.
Now at this stage of the course,
you probably feel quite comfortable with this method
because all the samples that we demonstrated
of the REST API included the version in the URL itself.
And actually, when discussing the best practice
for constructing the API URL,
we explicitly mentioned the version
as a component that must be included in the URL.
So this is one
of the most common forms of versioning in the API.
Another form is to put the version in the header,
something like this.
So if you see here,
the URL itself does not contain the version.
You can see at the top row of the example
that the URL contains only users,
and the number three,
which is probably some kind of an ID.
The accept header contains the version
that the client is using.
In this case, v1.
So this is another method.
And the last one is to put the version
in a query parameter like this.
So you see here that the URL itself, the base URL,
does not contain the version, but the version comes
as a query parameter after the question mark.
In this case, this is version4.
So these are the three forms
of specifying the version in the API.
Now, the question of course, is which one to use?
Which form of versioning
is the one we should pick with our API?
So the header form is the most correct form.
And the reason for that is that putting the version
in the header adheres to the REST principles.
Now what this means is this.
If you remember when discussing the REST principle,
we said that REST is an actual representation
of a resource of an entity,
so that when looking at a URL,
we know that this URL is the identity of a resource.
Now, putting the version in the URL
is in some way contamination of the URL,
because putting the version in the URL
means that there is an additional information
in the URL besides the identity of the resource.
And this is not what REST is all about.
So according to the REST principles,
the URL must represent only an entity
and not any additional information.
So from the best practices point of view,
the version should come in the header.
However, URL is the most common and easiest to implement,
and this is also
the reason why we specified the version in the URL.
As you saw for yourself,
integrating the version in the URL is extremely easy,
it requires no additional development effort,
and it also makes the URL very self explanatory.
So when a developer will look at the URL,
she will know immediately what is the version
of the API this URL is referring to.
Now whatever method you will choose,
do not use query parameters.
They query parameters method is the worst one.
And this is also the reason why almost nobody is using it.
So refrain from using query parameters for versioning.
So the bottom line is this.
In order to implement and integrate versioning in your API,
put the version either in the header or in the URL,
and never in the query parameters.
Now between the header and the URL,
practically, whatever method you will choose will be fine.
And of course, always specify the version.
You have to have a well defined versioning policy
for your clients, and they must be able
to specify which version they want to use.