The Chef’s secret sauce for API Versioning.

API Versioning is one of the most important ingredients of a successful API Strategy because is one of the most important touch points between API Providers and API Consumers.

No matter what REST book you read, you will have your API Versioning chapter. However most of the times the API Versioning chapters and articles explain how to implement it but rarely covers basic concepts like why API Versioning is needed and when is the best moment to do it.

The Chef’s secret sauce for API Versioning tries to fill this GAP and put everything together attempting to provide a 360º view of this topic from basics to implementation.

Sauce ingredient 1: Understand Why

There are a lot of ways of defining what APIs are but the one that will help us to achieve the secret sauce mastery is the one that defines an API as a Contract “a promise to perform described services when asked in specific ways”.

A Contract should never be broke unilaterally by none of the parties and the consequences of it will be always negative. Let me use the example of an apartment rental agreement where the lessor changes the price and remove some of the privileges unilaterally without any notify period. From a lessee perspective this will received negatively and probably will consider not to renew.

A poor API Versioning will lead to instability and will lead to friction with our API Consumers, the opposite, a solid API Versioning will lead to stability and improved developer experience. The same way than investors love market stability our API Consumers will love API version stability.

To consider your APIs as living Contracts ensuring the stability will give you the first and most important ingredient of the secret sauce of API Versioning.

Sauce ingredient 2: Know when

APIs are living Contracts and should be able to grow and improve in a continuous way however this will not mean contract breakage everytime so the key for preparing the secret sauce will be understand what changes implies contract breakage and what no. Remember, the more than an API Consumer will love is stability.

Let’s return to the apartment rental agreement example: Imagine a situation where a lessor starts allowing you to use a storage room without increasing the price or just change the Bank account for the monthly payments. The agreed service will be provided the same way without negative consequences from a lessee perspective, in fact in one of the cases the change is for start perceiving free additional services. The same will happen with changes in APIs.

• What changes will not break an API Contract?
  Non-breaking changes tend to be additive: Adding new fields or nested resources to your resource representations, adding new endpoints
• What changes will break an API Contract? Lead to API Consumer Friction!
  Breaking changes are changes that requires the API Consumer to make lockstep changes in order to continue consuming the API properly.
  Some examples are:
  - Delete a path.
  - Rename a path.
  - Delete/Rename parameters.
  - Add a constraint on a parameter (like isRequired).
  - Delete/Rename a request or response payload item.
  For going forward with the breaking changes we will need the deprecation of the current API Contract and the creation of a new Contract version. APIs are alive and this can be needed so the only way to minimize the consequences is a solid Communication Plan to help the API Consumer to plan when to integrate the new API Version.

Sauce ingredient 3: Decide how

Once we know how important API Versioning is and when to do it is time to decide how to implement it within the REST Principles.

We are not going to go in details of every type because there are a lot of stuff on the network so we will focus in share our choice for the secret sauce.

These are the possible types of API Versioning:

1. Custom header. e.g.: x-version: 1
2. Accept header. e.g.: Accept: application/vnd.example.v1+json
3. Query parameter. e.g.: http://domain/contracts-api/contracts?version=1
4. Path parameter. e.g.: http://domain/contracts-api/v1/contracts

The secret sauce’s choice is the path parameter approach because is widely used by most of the big players and most important is super easy for both consumer and provider. Sometimes simplicity is the answer.

In addition to decide the type of versioning will be also needed the format of the version value. The options available are:

1. Arbitrary strings like: 1.0-beta or 2017–07–25
2. Semantic Versioning like major.minor.patch. e.g. 1.2.0

• MAJOR version when you make incompatible API changes.
  This will be the value used by the API Consumer to call our APIs.
• MINOR version when you add functionality in a backwards-compatible manner.
• PATCH version when you make backwards-compatible bug fixes.

MINOR and PATCH values are transparent to the client and will be used internally.

The secret sauce’s choice is Semantic Versioning approach because is widely used, is flexible, you don’t need to break your head designing a versioning format and works really well with path parameter versioning type.

Summary

API Versioning is the most important touch point between API Provider and API Consumer. Doing it properly will lead to stable, solid and profitable relationship. Doing it wrongly will lead to instability, friction, negative consumer experience and ephemeral relationships.

The Chef’s secret sauce for API Versioning aims to provide the mindset, the tools and the knowledge to successfully implementing API Versioning in you API Program.

As uncle Ben said to Peter Parker (Spiderman) “A great power carries a great responsibility”

References:

https://pronovix.com/blog/what-api
http://stackoverflow.com/a/25545622/6653581
https://dzone.com/articles/api-versioning-methods-a-brief-reference-1
https://www.xmatters.com/integrations-blog/blog-four-rest-api-versioning-strategies/