Triggering Assure controls via REST API

Starting in Assure v9.1, Assure controls can be triggered via a REST API call. The REST API feature is in addition to the existing SOAP API feature - the SOAP API is not replaced by the REST API. This article covers the necessary setup to enable and use the REST API feature.

Enabling the APIs

The REST API feature is enabled by updating the following property to true within your Assure server's IA.properties configuration file. 

START_API_PROCESSORS=true

After the change is made, a validation and deploy will need to be run for the change to take effect. 

REST API Endpoint

The REST API to trigger controls requires a POST request with the body of the request containing JSON to trigger a specific control.

The REST API endpoint is below. Note that the context root (/infogixassure/) is not needed.

Endpoint Syntax:

http(s)://<assure-server>:<assure-port>/casapi/services/ExecuteControlPoint

Endpoint Example:

http://supsrv1.infogix.com:8080/casapi/services/ExecuteControlPoint

Authorization

Authentication is in basic format via the header. The username and password should be in base64 format of the following syntax:

username:password

For example, if your username and password are both admin, the syntax would be:

admin:admin

Which translated into base64 is: 

YWRtaW46YWRtaW4=

And the final basic authorization header would look like:

Authorization: Basic YWRtaW46YWRtaW4=

JSON Body syntax

The JSON body is what is posted to the REST API to trigger control execution. The body has several fields available for use, which are outlined in the Assure API Guide within the Assure documentation. The example below covers the essential fields.

Required JSON body fields:

• controlEntityName
  • The name of the control entity to trigger
• controlPointName
  • The name of the control point to trigger
• sourceTimestamp
  • The time the API was called by the client. This field is not currently used; however, it is required for future use.  

Common JSON body fields:

• waitForResponse
  • A boolean field indicating whether the client-side API call should wait for a response from the Assure Server upon control completion
• timeout
  • A millisecond value of how long to wait for a response, if the above field is set to true. This defaults to 10,000 milliseconds if it isn't set. If the API request times out, the control will still process server-side. Only the client-side will stop listening for a response.

Additional fields are available and are documented within Assure's API guide. Assure's API guide can be found within the documentation PDF portfolio within Assure's documentation page.

JSON Body example:

{
"controlEntityName":"sampleEntity",
"controlPointName":"samplePoint",
"sourceTimestamp":"2019-05-03T14:00:00.001-05:00",
"waitForResponse":"true",
"timeout":60000
}

In addition to posting the JSON body, the content-type header should be set to application/json to specify the type of request being posted:

Content-Type: application/json

cURL example

The curl command below combines the sample information above into a single API call to trigger a control. The API call can also be made from other sources besides a command-line execution, such as Infogix Data3Sixty or any other tool with REST API functionality. 

curl http://supsrv1.infogix.com:8080/casapi/services/ExecuteControlPoint -H "Authorization: Basic YWRtaW46YWRtaW4=" -H "Content-Type: application/json" -d "{\"controlEntityName\":\"sampleEntity\",\"controlPointName\":\"samplePoint\",\"sourceTimestamp\":\"2019-05-03T14:00:00.001-05:00\",\"waitForResponse\":\"true\",\"timeout\":60000}"