-: Our next topic is versioning.
Now, versioning is also a very important aspect
of API design, as in often overlooked by API designers.
So what is so important
about versioning in API.
When designing API,
one of the assumption you have to make is
that your API will be updated over time.
This update can include many things such as adding actions,
removing actions, and of course changing actions such as
adding parameters or removing parameters.
Now, this is fine, but
we always have to remember
that we do not control our clients.
The ones who are using the API
we don't know who they will be.
We don't know what tools and what clients they will use.
We don't know what is their upgrade life cycle
and we definitely
cannot force the client to
upgrade the version of their clients they are using.
So if one of our clients develop the API client
against a specific version of the API
and the API
is now
modified then this specific client will stop working
and we definitely don't want that to happen.
We always want to make sure our clients can actually
continue using our API.
So what can be done?
Well, there are two things that should be
done regarding versioning in in the API.
So the first one is to set a version support policy
for each version of the API.
We must clearly state what is the supported lifetime
of this version.
For example, take a look
at this API end of life statement from Salesforce.
As you can see, Salesforce clearly states
that each API version is supported
for a minimum of three years from the date of zero release.
Now, this document doesn't mention what happens
after the three years
but clients must assume that after three years
the version they are using will not be supported anymore.
Now, having this document gives a peace
of mind to the client.
They know that when a new version is released
then the version they're currently using will be supported
for at least another three years
and this will give them plenty
of time to adapt to the new version.
So setting a version support policy is the first
thing that should be done regarding versioning.
The second thing is to include the versioning
in the API itself,
and in the next lecture we will see exactly how to do it.