REST API
|
|
Sends a request for data retrieval, modification, or deletion to a RESTful API, and then stores any data returned in the response for use elsewhere in your script. |
For example, you can connect to an API web service that provides customer membership data such as personal and membership details. You can then store this data and play or send some or all of it to the calling party.
The action cell extends the REST connection method provided by the Web Service action cell by allowing complex data (rather than flat JSON data) to be passed to the API via an object variable in the HTTP request body. The data is converted to JSON format automatically. The action cell can store returned data in a variable (object variable type or otherwise) for use in other parts of your service.
Note: if network whitelisting is enabled in your storm deployment, ensure that Content Guru is included in your whitelist.
Properties
REST API Section
Use this section to configure the HTTP request body using a variable.
Note: requests over HTTPS require a Certificate Authority (CA) signed certificate. Content Guru does not support self-signed certificates.
|
Option |
Description |
|
Endpoint |
Enter the fully qualified endpoint address of the API to be called (a literal value preceded by =, or a string variable). For example, '=https://api.servicing.com/customers/portfolios' |
|
HTTP Verb |
Select one of the following HTTP request methods: GET to retrieve data from the API endpoint. POST to send the data in Request Body to the API endpoint. DELETE to delete data at the API endpoint. PUT to create or update data at the API endpoint with the data in Request Body. PATCH to partially modify data at the API endpoint with the data in Request Body. |
|
Request Body |
Applies to the POST, PUT, and PATCH request methods only. (Optional) The body of the API request. This must not exceed 20KB. This must be a value that is provided as a literal preceded by =, or a variable of the correct type. If you specify an object variable, ensure that you have populated the object's members with suitable values using other action cells. The REST API action cell will create a JSON string representation of the object at run time. |
|
Timeout |
Select the duration for which to wait for a response to the HTTP request. This must be in the range 1 to 60 seconds. If no response received in this time, the request to the configured endpoint is cancelled, and the Timeout exit route is taken. |
Authentication Section
Use this section if access to the API requires authentication. A simple Bearer Token authentication method is provided. 'OAuth' and 'JSON Web Token' methods may also be available for you to select if these profiles have been configured by Content Guru for your organisation.
Alternatively, you can use your own custom authentication method. A custom authentication method requires custom development by Content Guru and may incur a cost.
|
Option |
Description |
|
Enable Authentication |
Select this check box if the API requires authentication. |
|
Authentication Method |
Select the Bearer Token, OAuth, JSON Web Token, or the custom authentication method. |
|
Bearer Token |
Displayed if the selected authentication method is 'Bearer Token'. Specify the bearer token. This must be a value that is provided as a literal preceded by =, or a string variable. |
|
OAuth Profile |
Displayed if the selected authentication method is 'OAuth'. Specify the preconfigured OAuth profile to use. Your OAuth provider must use the client credentials grant type. |
|
JSON Web Token |
Displayed if the selected authentication method is 'JSON Web Token'. Specify the preconfigured JSON Web Token profile to use. |
Request Headers Section
Use this section if you want to provide extra information about the request context (for example, to tailor the API response).
In the Name field, enter a label for the parameter to pass. In the Value field, provide the value to pass as a literal value preceded by '=', or a string variable.
Click ADD to add the Name and Value pair to the list below.
Note: some headers, such as Content-Length are set automatically whilst others such as Cookie, Origin, and Feature-Policy are protected for security purposes and cannot be overwritten. You should not use these to populate this section as they will be ignored. See https://developer.mozilla.org/en-US/docs/Glossary/Forbidden_header_name.
Outputs Section
Use this section to store the result returned by the API.
|
Option |
Description |
|
HTTP Status Code |
An integer variable to hold the HTTP result code returned by the API. The code indicates whether the HTTP request passed or failed (including how it failed) so that you can provide special handling for particular failure cases. |
|
Success Response Body |
(Optional) Specify a variable of the appropriate type to store the body of the API response if the HTTP request is successful (that is, if a HTTP Status Code of 2xx is received). This is limited to 20KB. If you do specify a variable, the action cell will attempt to parse the parameter value in the API response to the correct FLOW variable type. For example, if a parameter value of "5" (enclosed in quotation marks) is received and the FLOW variable is of type integer, the action cell will parse the value as an integer. See also, the first note about object variables below this table. If a parameter value cannot be parsed, execution proceeds along the Invalid Response exit route. |
|
Failure Response Body |
(Optional) Specify a variable of the appropriate type to store the body of the API response if the HTTP request fails (that is, if a HTTP Status Code other than 2xx is received). This is limited to 20KB. If you do specify a variable, the action cell will attempt to parse the parameter value in the API response to the correct FLOW variable type. See also, the first note about object variables below this table. If a parameter value cannot be parsed, execution proceeds along the Invalid Response exit route. |
|
Invalid Response Log |
(Optional) Specify a variable of type string to store the log entry from the API indicating where parsing failed when the parameter value in the Success Response Body or Failure Response Body properties could not be parsed and execution proceeded along the Invalid Response exit route. This is useful in debugging errors in the action cell configuration. An example of a log entry that might be written to this variable is "Failed to parse 'True' as Date". Note: if there are multiple parsing failure errors, only the first of these is written to the variable. |
Note: if you are using an object variable to store the response, you should ensure that the number of members in the object matches the number of parameters returned in the response body. If there is a mismatch, then returned parameter values without an object member will be ignored by the action cell. And, parameters expected by object members but missing in the response will cause those object members to be populated by default values (for example, 0 for integers).
Note: date/time variables (in ISO 8601 format) are converted to the storm date/time format. For example, on a platform in British Summer Time (BST), the date/time "2021-06-20T10:00:00+06:00" is converted to “2021-06-20T05:00:00”.
Exit Points
|
Exit Point |
Description |
|
Success |
This is taken if the HTTP request has been sent and a HTTP Status Code of 2xx (for example, 201, 201, 205) is received. |
|
Failure Response |
This is taken if the HTTP request has been sent and a HTTP Status Code other than 2xx is received (for example, 4xx or 5xx). |
|
Invalid Response |
This is taken if the variable type specified in the Success Response Body or the Failure Response Body does not match the type of the returned data. For example, you may have specified a string variable type for one of these properties but the API returned an object type. |
|
Timeout |
This is taken if no response is received within the timeout period specified in Timeout. |
|
Error |
This is taken if there is a general error such as a network failure or an internal error. |
Example
|
|
|
 |
The configuration example shown on the left creates the HTTP request shown below. The object variable objRequestObject contains data members as shown in the JSON-formatted section of the request.
|
Note: In the header, 'Host', 'Content-Type' and 'Content-Length' are auto-generated headers and will always be present.
POST / HTTP/1.1
Host: www.google.com
Content-Type: application/json; charset=utf-8
Authorization: Bearer abc
Content-Length: 595
X-Custom-Header: def
[any additional auto-generated headers for Content Guru internal purposes]
{
"szString": "value",
"lInteger": 3,
"bBoolean": true,
"fFloat": 67.89,
"dtDateTime": "2020-12-18T12:00:00",
"objObject2": {
"arrintIntegerArray": [1, 2, 3],
"arrszStringArray": ["value1", "value2", "value3"],
"arrbBooleanArray": [true, false, true],
"arrfFloatArray": [10.1, 15.42, 7.0],
"arrdtDateArray": ["2020-12-18T12:00:00", "2020-12-19T12:00:00", "2020-12-20T12:00:00"]
},
"arrobjObject3Array": [{
"szString": "value1"
}, {
"szString": "value2"
}, {
"szString": "value3"
}]
}