Rest Api

Rest Api Action icon

Handles RESTful API calls synchronously. This action enables the system to handle higher loads. It returns both the body and headers for the API call. This makes it easier to test and debug scripts.

You can test a script containing a REST API action and view response information. To do this, run the script using the start with trace option.

You can also make synchronous RESTful API calls using the GetRestProxy() function in a SNIPPET action. This option doesn't handle high loads as well as the REST API action and is not the preferred method.

This action is one of the supported methods of connecting to web services in a Studio script.

Dependencies

There are limitations on the use of this action that are imposed at the business unit High-level organizational grouping used to manage technical support, billing, and global settings for your CXone environment level. This is done so that one should not impact the other. The limitations within the platform are:

Response Format: Only JSON response format is supported.
Retries on Failure: Action handler will automatically try two times if a failure message is received before returning the response.
Timeout: You specify the timeout value in the request. The value cannot be more than 90 seconds.
Max Response Size: The maximum response size is 32 KB. This is consistent with existing Snippet functionality. If you're reaching this limit, you must reduce the size of returned data.
Throttle Limit: The throttle limit is defined by two parameters:
- Max Concurrent Requests: Up to 100 concurrent requests are allowed by default. This limit is the same for all CXone customers. This means that 100 concurrent requests result in much higher throughput than the making API calls from a Snippet action. If you need more than 100 concurrent requests, talk to your CXone Account Representative about increasing the limit for your business unit. Special approvals are required.
- In Queue Count: When requests exceed the limit, the extra requests enter a processing queue. Once requests drop below the limit, queued requests are processed.
Circuit Breaker: If your specified URL is down or unreachable, you can get too many failures on your request. When this happens, CXone will reduce request execution of ALL URLs from the REST API action for a period of time. This allows your specified URL to recover from the failure. Limits are identified below:
- Back Off Time or Duration of Break: If the failure rate is reached, no requests from the REST API action will execute for 30 seconds.
- Minimum Throughput: 100 requests per second. If your business unit is not executing the minimum number of requests, it will continue to execute your requests even though the requests are failing.
- Failure Rate: If 50% of the requests failed during 30 seconds, your requests will not be executed for the following 30 seconds. 30 seconds is a rolling window.

Other dependencies of this action are:

JSON is the only supported response format. The action requires that all JSON be on a single line. When working with JSON in this action, you can:
- Do variable substitution from a string containing JSON.
- Convert a dynamic data object to JSON is supported using the asjson() function. Note that asjson() treats everything as a string, which means some manipulation is required when working with boolean or numeric values.
- Pass the output variable resultSet(out) from a previous REST API action to this property as well.
Responses are returned as jtoken objects. You can work with them just as you would with dynamic data objects in your script.
Responses contain headers and the body of the response. They may also contain HTTP status codes. Not all responses will include status codes. If there is no error, if the REST API action fails to generate a valid response, or if the error returned cannot be parsed as a valid response, no status is included.
You can use more than one REST API action in a script, but they cannot both reference the same objects.

Input Properties

These properties define data that the action uses when executing.

Property	Description
Caption	Enter a short phrase that uniquely identifies this action in the script. The caption appears on the script canvas under the action icon. The default is the action name.
Verb	Supports basic REST actions such as GET, PUT, POST, DELETE, and PATCH.
Parameters	Allows you to specify query parameters or post any data. Many kinds of JSON are acceptable, such as Jobject , Jarray, or Jtoken.
Headers	Allows you to add custom headers to allow for customer authentication, such as bearer tokens. You can use JSON in this field. Important If your custom URL endpoint requires different headers, it must be specified in this property. To keep feature parity with the existing Snippet action, CXone adds the following headers: {"Accept":"application/json", "Content-Type" :"application/x-www-form-urlencoded"}
Command	Currently the only option is MakeRestRequest. This functions the same as the MakeRestRequest()function used when making a REST API call in a Snippet action.
TimeOutInMilliSeconds	Allows a timeout of the REST call to be specified and honored. Must be less than 90 seconds (90000 milliseconds). If no timeout is specified, the default is 10 seconds (10000 milliseconds).
Service Address	The URL of the REST API you want the action to call. You can use variable substitution with this property.

Output Properties

These properties contain variables that hold data returned from executing the action. They're available for reference and use when the action completes.

Property	Description
resultSet(out)	A variable that holds any information returned from the API specified in Service Address. You can pass the contents of this variable as-is into the header and parameters if needed. The response is returned as a Jtoken object, but you can declare it as a dynamic object and work with it as you would other dynamic objects in your script.
errorArgList(out)	A dynamic data object that holds information about any errors that occur. When an error occurs, the object holds the HTTP status code, status description, and a message. When there is no error, the object is empty. HTTP status codes and descriptions are only returned in the error can be properly parsed as a valid repsonse. This means that not all errors will include an HTTP response code.

Property

Description

resultSet(out)

A variable that holds any information returned from the API specified in Service Address. You can pass the contents of this variable as-is into the header and parameters if needed. The response is returned as a Jtoken object, but you can declare it as a dynamic object and work with it as you would other dynamic objects in your script.

errorArgList(out)

A dynamic data object that holds information about any errors that occur. When an error occurs, the object holds the HTTP status code, status description, and a message. When there is no error, the object is empty.

HTTP status codes and descriptions are only returned in the error can be properly parsed as a valid repsonse. This means that not all errors will include an HTTP response code.

Result Branch Conditions

Result branch conditions allow you to create branches in your script to handle different outcomes when an action executes.

Condition	Description
Throttle	Path taken when too many requests are executed within a short period of time. See limitations below for more details.
InvalidInput	Path taken if invalid input is found or a timeout error occurs. Every parameter is validated when the script is saved.
Failure	Path taken when any error or exception happens within the NICE CXoneapplication executing the request.
Error	Path taken when the remote customer endpoint returns an http error code.
Default	Path taken when the response is not received within 90 seconds.
Success	Path taken if the action completes without errors and any API calls or data returns were successful (2xx response codes).