Usage of Operations REST API

You can access the System Automation Operations REST API by sending standard HTTPS requests to the configured port. Then the Operations REST API returns the response that contains a header and also a body for GET requests. The header contains a standard HTTPS return code and the body for GET requests contains a JSON data structure.

The HTTPS requests sent to the Operations REST API can contain either one of the verbs: GET, POST, or DELETE.

GET: GET is used to query for some information. When the call is successful, a response body is returned, such as an array of JSON objects that represent those resources you want to get information about.
The returned array might be empty, even if the return code indicates a success. In this case, no object is found that matches your specified filter.
POST: POST is used to request some actions from System Automation, such as, issuing a start or stop request to a resource, or creating a new dynamic resource from a template.
DELETE: DELETE is only available to delete a dynamic resource that is identified by its ID. A dynamic resource can be one that is created from a template either by using a POST request or calling the INGDYN command manually.

You can issue the HTTPS request either through the built-in Swagger UI of the Operations REST API, or by issuing the curl command in a CLI.

Using the API in Swagger UI

Detailed information of how to specify the HTTPS requests is provided in the Swagger UI, and you can view it with a standard Web browser by using the following URL:

https://<SA_SERVER_HOST>:<SA_SERVER_PORT> /ibm/sa/swagger-ui.html

You can access the Swagger UI and execute requests only after you have configured and started the Operations REST Server component (see Planning and Installation). However, if you want to preview it before installing Operations REST Server, you can refer to Documentation of Operations REST API.

Using the API with curl commands

The following examples use the curl command to send an HTTPS request to the System Automation Operations REST API. This curl command is available on most Linux® or UNIX systems that you use as REST clients. For Windows, you might look for an alternative. Although Windows 10 also comes with the curl command, the syntax of using it might be different to the following examples.

Example 1: Get all templates defined in current active automation policy

In this example, basic authentication is used to GET a list of all defined templates.

curl -s -k -u <USER_ID>:<PASSWORD> -X GET  https://<SA_SERVER_HOST>:<SA_SERVER_PORT>
/ibm/sa/v1/templates'

Once it is successful, the return code is 200 (success) and a body document contains an array of templates in JSON format.

Example 2: Create a dynamic resource from a template

In this example, a POST request is used to create a dynamic resource instance from a template. The template ID and the data that is required to create this instance is specified with the -d parameter of the curl request.

curl -i -k <USER_ID>:<PASSWORD> -H "Content-Type: application/json"  -d 
'{"templateId":"abcdef123ghi345","subsystem":"SUBSY1","system":"SYS01","job":"TESTJOB"}' 
-X POST 'https://<SA_SERVER_HOST>:<SA_SERVER_PORT>/ibm/sa/v1/resources'

Example 3: Check the status of a resource

In this example, a GET call is used to retrieve the information about a specific resource. The specific resource ID, opqe789klmnopq3e4 in this example, is either returned from the POST call as shown in example 2 or can be retrieved by listing all resources (not templates) similar to example 1.

curl -i -k -u <USER_ID>:<PASSWORD> -X GET 'https://<SA_SERVER_HOST>:<SA_SERVER_PORT>
/ibm/sa/v1/resources/opqe789klmnopq3e4'