When we first introduced the MQ REST API in 9.0.1 we included a version number in the URL. For example a GET to the following URL can be used to list the queues defined to the queue manager called qmgr1:
The version is the bit in bold: v1, so version 1.
So far we have kept the version the same throughout all the continuous delivery (CD) releases, even though we have been adding lots of new function to the REST API, and occasionally changing function that we have already released.
You might reasonably ask, given the scale of changes in CD, when would we change the version number? That is the question this blog is meant to answer.
First, however, I want to define what we consider a breaking, or non-breaking, change to the REST API to mean.
A breaking change is anything that will result in the REST API returning a response, which might include an error, which is different to what was returned before.
I.e. a breaking change is anything that:
• Removes support for an existing attribute in JSON that is sent to, or returned from, the REST API
• OR removes a URL, HTTP verb, or header – this removal might be the result of that URL or header being renamed or a different verb being used
• OR adds a new mandatory JSON attribute to data which is sent to an existing URL
• OR adds a new mandatory HTTP header to data which is sent to an existing URL
• OR adds a new mandatory query parameter to an existing URL
In contrast, non-breaking changes are additive changes to the existing REST API. Clients of the REST API should be written to expect and tolerate these changes. Much like users of PCF need to tolerate new attributes being added to responses from time to time.
A non-breaking change is anything that:
• Adds a new JSON attribute to existing data that is returned from the REST API
• OR adds a new URL
• OR adds a new HTTP verb, or status code, on an existing URL
• OR adds new optional JSON attributes, query parameters, or headers to data which is sent to an existing URL
• OR returns new headers from the REST API
When we put out the next long term support (LTS) release the REST API will remain at version 1. In the CD releases after that we will keep the version number at 1 when we make non-breaking changes. However, if we need to make a breaking change to the REST API we will:
1) Stabilise the existing function of the REST API, including any non-breaking changes made in CD, at version 1, but not include the breaking change
2) Increment the version of the REST API to 2 and make the breaking change in the new version of the REST API
The version 1 variant of the REST API will not be changed further and will remain supported in production environments. Subsequently we might deprecate that variant, and then remove it in a future LTS release.
We will not increment the version number more than once between consecutive LTS releases, regardless of the number of breaking changes we make.
This process will continue through subsequent CD and LTS releases.
Here is an example, which hopefully clarifies things:
• LTS release X: REST API is at version 1
• CD release X.0.1: support for a new URL is added. This is a non-breaking change. REST API remains at version 1
• CD release X.0.2: support for a new URL is added. This is a non-breaking change. REST API remains at version 1
• LTS release Y: REST API is at version 1
• CD release Y.0.1: an existing URL is renamed. This is a breaking change. The URL keeps it existing name in the version 1 variant of the REST API. A new version of the REST API, version 2, is created. The renamed URL goes into version 2 of the REST API along with all the function that didn’t change. Any subsequent new function in the REST API is added to version 2. Version 1 is stabilised at the level in LTS release Y
• CD release Y.0.2: an existing URL is renamed. This is a breaking change which goes into version 2 of the REST API. Version 1 is stabilised at the level in LTS release Y
• LTS release Z: REST API remains at version 2. Version 1 is stabilised at the level in LTS release Y
Hopefully that makes sense! If not please add comments and I will get back to you.
The rules described above are designed to allow us to grow the REST API during CD releases, while maintaining the stability that our customers demand. Just remember to code your applications to allow for the fact that we will make non-breaking changes.