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}"
Comments
0 comments
Please sign in to leave a comment.