Restful APIS Versioning Methods

When it comes to REstful API versioning, there are a conflicting views exist in the industry, from versioning to not to version at all. But everyone is in consensus that an API can grow over time making the interface unbale to work with existing client resulting in a break change. Here we will look in to versioning options of Restful APIs and guidelines to follow.

When to Version

When an Restful API released, it will address the use cases given that time. With proactive design, a lots of upcoming needs could also be considered at this time. But eventually it will come to a point the interface has to change to accommodate the new realities and challenges.

When change of an API results in breaking of existing client, it is called a break change. You need versioning approaches when it comes to break changes.

Versioning due to Format Change

A Rest API could decided to change the format of the entity, if the situation demands it. In such cases, there is no way for the client to work seamlessly without adhering to the the new format. This is a situation where API interface went beyond adding some extra attributes to the entity. Such format changes result in a break change.

Versioning due to Entity Change

In other situations, the upgrade of a Rest API can result in fundamental change in the entity or the resource it works on. Definitely this is a break change.

Restful API Versioning approaches

Versioning REst API

Roy Fielding who is the creator of REST Services has his suggestion on versioning. His approach is that a Rest API should be considered just like a website and should not be versioned at all, similar to the way you do not have separate version of the same website. If you create a new website, it should a different website. Similarly, if an API changes beyond its original intent, it must be considered as a new Entity, thus resulting in a new Restful API itself.

However, industry has its own take when it comes to API versioning. All the major API enablers support API versioning. So the developer community and enterprises at large have aligned with versioning REstful API. We will consider, Roy Fielding approach also as one of the versioning techniques in the following sections.

Versioning with URI

Example:

http://api.mydomain.com/1/entities

Here the versioning is shown numerically.  This is a very straight forward way to version a Rest API. The changes are obvious and URI has changed to reflect the changes. As the best practice the version number need to include only the major number that include break change.

Pros:

  • Change is visually obvious
  • Since URI has changed, the cache replacement, if any, will work without any additional effort

Cons

  • If you decided to make the API change with a break change, there are efforts comes along with this including source code management. It is not a con per se.


Versioning with Query Parameter

Example:

http://api.mydomain.com/entities?version=1

The changes are obvious here as well - you add versioning number as a query parameter.

Pros

  • Visual Change and easy

Cons

  • query parameters do not force an automatic cache clear

Versioning through Custom Header

You can create a custom header to indicate the version change. 

Example:

My_Custom_Accept: version1

Use any reasonable name instead of My_Custom-Accept, it is simply the name of the header you created to communicate the version change.

Pros:

  • No URI Change and if you any layer in between such as an API Enabler, the routing is easy

Cons:

  • Version is not visually obvious
  • Any other issue of using a different version under the same URI

Versioning through Content Negotiation

Restful API can present the same entity in differently and a client can negotiate with the server, the presentation it wants. This is the concept in the content negotiation. The standard header - Accept Header, is used for content negotiation.

This approach could be used here for versioning also. The client simply asks for the right version during the content negotiation.

Thus you Accept Header would become similar to:

Accept: application/vnd.myentity+json;version=1

Pros:

  • URI remains the same. If you are using API Enablers or similar routing is seamless.

Cons:

  • Not widely used method.
  • API changes are not visually obvious

Versioning as New Entity

In this approach, we align with Roy Fielding's suggestion. The change is considered as a totally new Entity and thus results in a totally new API. Instead of a version number, the new name of the entity is used.

http://api.mydomain.com/new_entities

Versioning standard

When it comes to versioning, it is mandatory that a standard is followed. Major industry players follow Semantic Versioning standard and thus it makes sense to follow in your API versioning too. But the clients should only need to update when breaking changes happen

Semantic versioning standard suggest versioning of the format: MAJOR.MINOR.PATCH - for example 1.2.3.

MAJOR - version number indicating a break change and impacts existing clients.

MINOR - Changes have happened, but it is backward compatible and thus it does not break existing clients. 

PATCH - smaller changes such as bug fixes, this do not break existing clients.

If you look these versioning, only the major versioning number is the one that will cause a break change. If you include the whole version in your versioning method - URI to Header, this will mean your client will have to adjust with such changes.

 As a best practice, you may include only the MAJOR version number no matter the versioning technique used. The Semantic standards as still valid and you could use it internally to run multiple APIs or microservices. 

This article covered all the details you need to know when it comes to Restful API versioning. Do you use any other method or any suggestion you might want to share? please leave a comment.


{"email":"Email address invalid","url":"Website address invalid","required":"Required field missing"}