+

Search Tips | Advanced Search

REST API versions

The REST API version number forms part of the base URL for REST requests. For example, https://localhost:9443/ibmmq/rest/v2/admin/installation. The version number is used to isolate clients from changes to the REST API that might be introduced in future releases.

Version 9.2.0 introduces version 2 of the REST API. This version increase applies to the administrative REST API, messaging REST API, and MFT REST API. This version increase changes the resource URL that is used for the REST API. The URL prefix for the resource URLs at version 2 is the following URL:
https://host:port/ibmmq/rest/v2/

Some changes that are introduced to the REST API might change existing REST API function such that clients that use the REST API might need to be updated. To prevent such changes from forcing clients to be updated, the REST API version number is increased, and existing function stabilized at the previous number. The new function that might change the existing function is added to the REST API at the new version number. Therefore, clients can continue to use the REST API at the previous version without being updated.

The REST API changes that might result in requiring a client update includes the following changes:

  • Removal of support for an existing attribute in the JSON that is sent to, or returned from, the REST API.
  • Removal of a URL, HTTP verb, or header. For example, if a URL or header is renamed, or if a different verb is used.
  • Addition of a new mandatory JSON attribute to data that is sent to an existing URL.
  • Addition of a new mandatory HTTP header to data that is sent to an existing URL.
  • Addition of a new mandatory query parameter to an existing URL.

When this type of change is introduced to REST API function that existed in a Long Term Support (LTS) release, the version number of the REST API is increased for the first of these changes. Any subsequent changes that are made within a Continuous Delivery (CD) release that might require changes to clients that use the REST API use the new version number.

This version number remains the same throughout subsequent CD releases until the next LTS release. Therefore, the version number increases at most once between LTS releases.

When the version number is increased, the existing REST API function is stabilized at the old version number. That is, the existing REST API function that was available at the LTS release remains available at the old version number, but no further changes are made to that version. Any new function that is added to the REST API is added to the new REST API version. However, any additions that are made to the REST API in CD releases before the version increase are not guaranteed to be included in the older version of the REST API.

Existing clients can continue to use the REST API at the old version number without requiring any changes. Older versions of the REST API might be deprecated, and eventually removed.

Some changes do not require changes to clients that use the REST API. These changes do not result in an increase of version number. Therefore, ensure that any client that uses the REST API does not need to be updated when these types of changes are introduced. These changes to the REST API might include the following changes:

  • Addition of a new JSON attribute to existing data that is returned from the REST API.
  • Addition of a new URL.
  • Addition of a new HTTP verb to an existing URL.
  • Addition of a new status code to an existing URL.
  • Addition of new optional JSON attributes to data that is sent to an existing URL.
  • Addition of new query parameters on an existing URL.
  • Addition of new headers to data that is sent to an existing URL.
  • Return of new headers from the REST API.


Changes to new Continuous Delivery REST API function

For new REST API function that is added in a CD release, any changes that are made to this new function that might then require changes to REST API clients do not increase the version number. That is, the new function can change before the next LTS release without increasing the version number. When the function is included in an LTS release, any subsequent changes that might require changes to REST API clients do increase the version number.


Example

  1. At LTS release X, the REST API is at version 1.
  2. At CD release X.0.1, support for a new URL is added. This change does not require changes to clients that use the REST API. Therefore, the REST API remains at version 1.
  3. At CD X.0.2, support for a new URL is added. This change does not require changes to clients that use the REST API. Therefore, the REST API remains at version 1.
  4. At LTS release Y, the REST API is at version 1.
  5. At CD release Y.0.1, an existing URL is renamed. This change might require changes to clients that use the REST API. Therefore, a new version of the REST API is created as version 2. The renamed URL is included in version 2 of the REST API, along with all the existing function. Any new function that is added to the REST API is added to version 2. Version 1 remains stabilized at the level in LTS release Y.
  6. At CD release Y.0.2, another existing URL is renamed. As the version is already increased in CD release Y, the REST API remains at version 2. Version 1 remains stabilized at the level in LTS release Y.
  7. At LTS release Z, the REST API remains at version 2. Version 1 remains stabilized at the level in LTS release Y.

Parent topic: Administration using the REST API

Last updated: 2020-10-04