Host factory RESTful APIs: An overview

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

Host factory RESTful APIs are available on the same management host that runs the HostFactory service. To provision and release hosts using RESTful API, ensure that the requestor instance initiating the request is enabled in REST mode in the hostRequestors.json. All other APIs can be accessed without any additional configuration.

The RESTful API interface is supported over both HTTP and HTTP over SSL (default). For its SSL 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.