Versioning

An API can be versioned in several ways, but this documentation is limited to the three most commonly used variants.

However, a correct implementation is indispensable in any way, since a later migration is usually associated with breaking changes and can thus render applications unusable!

Why is versioning needed?

Applications evolve, and so do their interfaces.

However, if an interface is used by other developers or applications, then you have to make sure that you don’t disrupt their operations when you evolve or generally change an API. Therefore, it is extremely important to develop a concept that makes it possible to handle changes in such a way that other applications do not crash abruptly.

The most common concept is multi versioning. This means that multiple versions of an API are available in parallel so that other development and applications can update to the latest version over time.

Such a multi versioning is usually implemented via the following three variants:

URI Path Versioning

With URI path versioning, the version is part of the URI.

> myapi.com/api/v1/tasks
> myapi.com/api/v2/tasks
> myapi.com/api/v3/tasks
> myapi.com/api/latest/tasks

This type of versioning is very easy to implement: in effect, each version is a separate endpoint. These multiple endpoints can be served either by a single application, or by multiple applications.

With multiple applications, the advantage is that each version is also independent of the runtime. So version 1 could be run with Java, and version 2 with .NET.

Another big advantage is that not only the operation but also the development is really isolated. If a certain period of time of an old version is exceeded, it can simply be switched off without interfering with the operation of the other versions.
This versioning is not only very simple, it is also very powerful and therefore very widely used.

The disadvantage of this versioning is that in the end a resource can have multiple URIs, since there are multiple API endpoints - and thus contradicts REST, in which each resource should have a unique URI.

However, this disadvantage is conceptually minimal and in most cases only theoretical.

HTTP Header Versioning

With header versioning, the server is told at the time of the request which version the client wants to work with against the API.

> Accept: Version=1
> myapi.com/api/tasks

Header versioning allows the URI to be decoupled with the version so that the URIs themselves also remain unique. This can be implemented either by the Accept header or by Content Negotation.

The big disadvantage of this variant is that it is very intransparent compared to URI versioning, and URL structure changes are extremely complex.
This versioning type has its advantages in certain scenarios when it is a very established and mature API. For growing APIs where restructuring can be expected, this causes frustrating problems among developers in most cases.

HTTP Query Parameter Versioning

With the HTTP query parameter, the desired version of the client is not sent via an opaque header field, but as a query parameter and thus immediately visible via the URI.

> myapi.com/api/tasks?version=1
> myapi.com/api/tasks?version=2
> myapi.com/api/tasks?version=latest

The disadvantages of this variant hardly differ from the header variant, but the dynamic query parameter also makes caching more complex.

Conclusion

• API versioning is the practice of managing changes to your API.
• For most APIs, versioning the URI path is the best practise solution.