Query API Version

Edit online

The Query API Version operation returns information about the level of Web Services API supported by the HMC. This operation is supported using the BCPii interface and when used in this way returns information about the SE rather than the HMC.

HTTP method and URI

GET /api/version

Response body contents

On successful completion, the response body is a JSON object with the following fields:

Field name Type Description
api-major-version Integer The major-version part of the API version in effect for this session
api-minor-version Integer The minor-version part of the API version in effect for this session
hmc-version String (5-8) The version number of the HMC firmware. This is a string of the form v.r.m, where each of v, r and m can be one or two digits. Example: "2.11.1".
Note: This field is only returned for requests targeting an HMC.
hmc-name String (1-16) The name assigned to the HMC.
Note: This field is only returned for requests targeting an HMC.
hmc-time Timestamp The current time, according to the HMC.
Note: This field is only returned for requests targeting an HMC.
se-version String (5-8) The version number of the SE firmware. This is a string of the form v.r.m, where each of v, r and m can be one or two digits. Example: "2.15.0".
Note: This field is only returned for requests targeting an SE.
se-name String (1-8) The name assigned to the SE.
Note: This field is only returned for requests targeting an SE.
se-time Timestamp The current time, according to the SE.
Note: This field is only returned for requests targeting an SE.
classification-text String (1-1024) The console's classification text. A null value is returned if the classification text is not set.
vendor String Enum The vendor that supplied the HMC. Non-IBM® vendors are identified in an abstract fashion rather than by company name. The valid values are:
  • "ibm" - IBM
  • "a" - vendor a
  • "b" - vendor b
  • "c" - vendor c
  • "d" - vendor d
  • "e" - vendor e
  • "f" - vendor f
  • "g" - vendor g
  • "h" - vendor h
  • "i" - vendor i
  • "n" - numeric vendor value, where n is an integer between 0 and 255. [Added by feature oem-hmc-ids]
welcome-text String (1-8192) The console's welcome text. A null value is returned if the welcome text is not set.
reflow-welcome-text Boolean Indicates whether to format the welcome text to fit the width of the user's browser window.

Description

This operation returns name and version information for the HMC or SE and the API itself.

This operation can be requested without an API session being open, i.e. no X-API-Session header, and session-id is required on input.

For more information about the function included in each API version, see Summary of API version updates.

HTTP status and reason codes

On success, HTTP status code 200 (OK) is returned and the response body is provided as described in Response body contents.

Under normal conditions, no error response codes are returned by this request. (HTTP Status code 500 could possibly result if internal HMC errors occur.)

Example HTTP interaction

Figure 1. Query API Version: Request
GET /api/version HTTP/1.1
Figure 2. Query API Version: Response
200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Wed, 16 Jun 2021 15:51:46 GMT
content-type: application/json;charset=UTF-8
content-length: 225
{
   "api-major-version":4,
   "api-minor-version":1,
   "classification-text":"Top Secret",
   "hmc-name":"HMC1",
   "hmc-time":1623858706738,
   "hmc-version":"2.16.0",
   "reflow-welcome-text":true,
   "welcome-text":"Sample welcome text",
   "vendor":"ibm"
}