REST API reference

The representational state transfer (REST) application programming interface (API) is provided by the system.

Each system exposes a REST API as there are no special configuration settings to enable or disable this interface. The Cloud Pak System REST API is available on the same IP address or hostname used to access the console and command-line interface. Unlike the console, the REST API is only supported over the HTTPS protocol on port 443. The system uses a self-signed certificate for its SSL sessions. The same certificate is used for console, command-line interface and REST API sessions. You need to configure your HTTPS client to either accept or ignore this certificate during the SSL handshake.

HTTP header requests

When generating HTTP requests to the REST API, pay special attention to the following headers:
Accept
With a few exceptions, the REST API generates JSON-encoded data in its responses. Include an "Accept: application/json" header in your request to indicate the ability of your client to handle JSON responses.
Accept-Language
Use this header on your HTTP request to specify which language or locale should be used by the system when generating the response data. You can specify any of the languages supported by the system.
Authentication
The REST API only supports HTTP basic authentication. After successfully authenticating, the server will return two cookies named zsessionid and SimpleToken that should be included with subsequent HTTP requests that are part of the same session. If requests are sent by using HTTP basic authentication rather than by forwarding the returned SimpleToken cookie, the server-side effort is increased for authentication and authorization. If the zsessionid cookie is missing from HTTP requests, a new user session is created for each new incoming request and more server-side resources are consumed as a result.

The same user IDs and passwords used to access the console and the command-line interface are used to access the REST API. The authorization of a user to perform actions on the system is independent of the interface (console, command line, or REST API) that is used to request the actions.

Content-Type
All the content included in an HTTP request body sent to the system must be JSON encoded. You must include a "Content-Type: application/json" header to indicate this for each request that includes any data.
X-IBM-PureSystem-API-Version: 2.0
Every HTTP request to the system must include a "X-IBM-PureSystem-API-Version: 2.0" header to indicate that your client expects the REST API semantics described in this document. See the following usage example:
curl --cacert cps_host_name https://cps_host_name/resources/addons -k -H "X-IBM-PureSystem-API-Version: 2.0"
where, cps_host_name is the hostname or IP address of your IBM® Cloud Pak System user interface.
X-IBM-Workload-Deployer-API-Version: 5.0.0.0
Every HTTP request to the system that uses a workload management REST API must include a "X-IBM-PureSystem-API-Version: 2.0" header or a "X-IBM-Workload-Deployer-API-Version: 5.0.0.0" header to indicate that your client expects the REST API semantics that are described in this document.

Supported data format

The REST API only supports the sending and receiving of UTF-8 encoded data. Ensure that your HTTP client is appropriately set to encode and decode character data, including JSON data. All responses of REST requests in JSON format are encoded in UTF-8.

Controlling the records in API response JSON

You can use the query parameter to make sequential calls to get the total number of objects in chunks. The records are controlled in the API response JSON.

By default, the REST API JSON response contains a maximum of 500 records. You can control the behavior by passing two query parameters to the REST API.
  • count
  • page
The appending of the ?count=<numberOfRecordsNeeded> query returns either as many records or all the records if the total number of records are less than numberOfRecordsNeeded. If numberOfRecordsNeeded is set to 0, it returns all the records.
Attention: If the total number of records that are retrieved exceeds 500, it might have performance issues on the overall system health.

The page query parameter can be used to retrieve the response in batches. For example, API /admin/resources/addresses?count=5&page=2 returns five records from the second set (6-10) of the IP addresses table.

Error codes

Error reporting for the REST API follows HTTP error code conventions, for example:
403
This code is returned if the requester has not been assigned the cloud administration role.
500
This code is returned if the system encountered an internal error while processing the request.
If the Accept tag in the request header is in application/json format, a JSON error object is returned:
{
   "errorStatusCode": 403,
   "message": "User is not authorized to perform this operation.",
   "errorMessage": "User is not authorized to perform this operation."
}