The representational state transfer (REST) application
programming interface (API) is provided by IBM® Cloud Orchestrator.
Before you begin
Each product exposes a REST API as there are no special
configuration settings to enable or disable this interface. The IBM Cloud Orchestrator REST
API is available on the same IP address or host name that is used
to access the product GUI and command-line interface.
Unlike the GUI, the REST API is only supported over the HTTPS protocol
on port 443. The product uses a self-signed certificate for its SSL
sessions. The same certificate is used for GUI, command-line interface and
REST API sessions. You must configure your HTTPS client to either
accept or ignore this certificate during the SSL handshake. You must
use an HTTPS client that allows you to set the HTTP headers for each
request. This is because there are multiple headers that are required
for authentication, authorization, and content negotiation.
To
comply with stricter security requirements, IBM Cloud Orchestrator enforces
the use of the fully qualified domain name (FQDN) to call the user
interfaces. You must use the FQDN to implement single sign-on. The
FQDN is also necessary for all HTTP POST and PUT operations, which
are used to submit all forms in the user interface, including the
login credentials. In emergency cases only: if the FQDN cannot be
used, you can disable the security check by removing the cookie_domain entry
from the /opt/ibm/ico/ccs/scui/etc/config.json file.
When
generating HTTP requests to the
IBM Cloud Orchestrator 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 must be used by the product when generating the response
data. You can specify any of the languages that are supported by
the product.
- Authentication
- The REST API only supports HTTP basic authentication. After successfully
authenticating, the server will return two cookies that are named zsessionid and SimpleToken that
must be included with subsequent HTTP requests that are part of the
same session. The same user IDs and passwords that are used to access
the GUI and the command-line interface are
used to access the REST API. The authorization of a user to perform
actions on the product is independent of the interface (GUI, command-line interface or
REST API) used to request the actions.
- Content-Type
- All the content included in an HTTP request body sent to the product
must be JSON encoded. You must include a "Content-Type: application/json" header
to indicate this for each request that includes any data.
- domainName
- When not using the default domain, the HTTP request must include
in the header "domainName:<yourDomainName>" to
let the user be authenticated to the <yourDomainName> domain.
- projectName
- When not using the default project, the HTTP request must include
in the header "projectName:<yourProjectName>" to
let the user be authenticated in the <yourProjectName> project.
The REST API is only supports the sending
and receiving of UTF-8 encoded data. Ensure that your HTTP client
is set to encode and decode character data, including JSON data. All
responses of REST requests in JSON format are encoded in UTF-8.
Note: Key-value
pairs that are only used by user interface clients are optional.