Host factory RESTful APIs: An overview

Use the RESTful application programming interface (API) to manage cloud bursting through host factory in IBM® Spectrum Symphony.

No special configuration is required to enable the RESTful API for host factory, except to access the requestor APIs that request hosts and release hosts; both these APIs require the requestor plug-in to be enabled in REST mode. All host factory RESTful APIs are available on the same management host that runs the HostFactory service. With the exception of the two requestor APIs, the RESTful APIs require the same permissions as the cluster management console.

The RESTful API is supported over both HTTP and HTTP over TLS (default). For its TLS sessions, the RESTful API client uses a self-signed certificate by default. This self-signed certificate can be used only for testing purposes. For your production environment, you must use a properly chained certificate that is issued or signed by a trusted certificate authority.

HTTP header requests

For authentication, the RESTful API supports HTTP basic authentication and credential authentication. Except the authentication APIs (/login and /renew), all APIs can be called with basic authentication. Successful authentication returns three cookies, named platform.rest.hf.token, platform.rest.hf.certificate, and hfcsrftoken. For credential authentication, the hfcsrftoken that is obtained from login must be passed as a request parameter for all POST, PUT, and DELETE requests.

Responses

After a successful command, most commands return either a simple string value or a JSON string. In addition to the result of the command, the commands return standard HTTP status codes. The following list includes the most common status codes that are returned:

Status code	Description
200 OK	General status if the request was successful.
401 Unauthorized	Could not authenticate user credentials or token.
403 Forbidden	User was authenticated but user is not authorized for the requested operation.
500 Internal Server Error	An internal error occurred. Log files must be checked. Look for hints in the API response body.