API versioning

Since the functionality of the Web Services API may evolve over time, each functional level of the API is identified by a version number and, beginning with version 4.10, a set of available API features. This version number is represented in major.minor form, with the initial version of the API designated as version 1.1.

The API version offered by an HMC can be determined before API logon by using the Query API Version operation (GET /api/version). The version number of the API is also provided in the response from the Logon operation. Beginning with version 4.10, the names of the available API features can be retrieved by using the List Console API Features and List CPC API Features operations. See API features for more information

Enhancements to the API specification that maintain compatibility with previous versions (see principles below) are indicated by incrementing the minor portion of the version number and/or adding to or removing from the set of available API features. So, for example, the first set of compatible changes to the API would be designated as version 1.2, following the initial 1.1 version. Beginning with version 4.10, the set of available API feature would be updated.

Because the minor versions within a major version stream (e.g. the 1.x versions) are considered compatible, the HMC always offers and behaves according to the latest minor version of the API specification it supports. That means, for example, the API does not offer any facility by which a client can request version 1.1 behaviors on an HMC that offers version 1.2 level of functionality. Nor can a client request behavior tied to the presence or absence of specific API features.

While reasonable effort will be made to preserve compatibility, it may become necessary to make changes to zManager (and thus the API) that do not maintain compatibility with the previous version. If this occurs, the introduction of this new (incompatible) behavior is indicated by incrementing the major part of the version number, and starting the minor part of the version number again at 1. The first such version would thus be identified as version 2.1. It is possible for an API feature that was available to later be removed, thus it is a good practice for a client to check feature availability if it depends on the functionality provided by a certain API feature.