# RESTAPICLIENT Workflow Application
## Overview
The **RESTAPICLIENT** workflow application allows you to call REST API endpoints to exchange information with other applications through HTTP requests, and can be used to build integrations with extendable applications (such as Azure Services and Slack).
It also allows you to call a REST API endpoint using `application/json` or `application/x-www-form-urlencoded` payloads. RESTAPICLIENT will then receive and process the response from the external API by mapping the response content with defined OUT parameters.
## How it works
* The RESTAPICLIENT application requires the `APP_URL` parameter, which corresponds to the REST API endpoint.
* The default request payload content type (`APP_REQUEST_CONTENT_TYPE`) is `application/json`. `application/x-www-form-urlencoded` is also supported.
* The default HTTP request method (`APP_METHOD`) is `GET`. Other request methods (`POST`, `PUT`, `DELETE`, etc.) are also supported.
* In case of error, when the `APP_RESPONSE_IGNORE_ERROR` IN parameter is defined and has `Y` as its value, the error will be ignored and defined OUT parameters (`APP_RESPONSE_STATUS` or `APP_RESPONSE_CONTENT`) will be mapped. Otherwise, an exception will be thrown.
* Since the application parameters are case sensitive, parameters must use the API’s accepted notation.
* The default request timeout is 30,000 milliseconds (30 seconds); this default value can be modified by setting the `RestApiClientRequestTimeout` parameter value in the `web.config` file. The request timeout can also be defined in the `APP_TIMEOUT` IN parameter; the maximum timeout is 3,600,000 milliseconds (1 hour).
✏️ **Note:** This timeout value must be less than the IIS request timeout value.
* The HTTP request headers can be defined with the `APP_HEADER_xxx` parameters, where `xxx` is the header field name. For more information, see the [Header parameters](#header-parameters) section.
* The request payload can be defined in the `APP_REQUEST_CONTENT_FILE` or `APP_REQUEST_CONTENT` IN parameters. When both parameters are defined, the `APP_REQUEST_CONTENT_FILE` parameter has priority. For more information on these parameters, see the [Request payload](#request-payload) section.
* The response from the REST API can be mapped to the `APP_RESPONSE_CONTENT_FILE` or `APP_RESPONSE_CONTENT` OUT parameters. Both parameters can be defined at the same time. For more information on these parameters, see the [Response payload](#response-payload) section.
* Besides the optional parameters listed below, you can also add additional custom IN and OUT parameters to send and receive custom user-defined data to and from the external API. For more information on and examples of these custom IN and OUT parameters, see the [Request payload](#request-payload) and [Response payload](#response-payload) sections.
* The application supports the JSONPath query language (see [https://github.com/json-path/JsonPath](https://github.com/json-path/JsonPath/)), which allows extraction of specific data from a JSON response (similar to XPath expressions in XML). For information on how to use this with the application along with examples, see the [Response payload](#response-payload) section.
* Application logs are available and can be specified by setting the `RestApiClientLogLevel` parameter value in the `web.config` file to `0` to disable logging (default), `2` for simple logs, or `3` for debug logs.
* The default maximum response length is 4194304 characters (4 MB); this default value can be modified by setting the `RestApiClientMaxResponseLength` parameter value in the `web.config` file.
* Automatic deletion of temporary files can be disabled by setting the `RestApiClientEnableFilesCleanUp` parameter value to `N` in the `web.config` file; the default value is `Y`.
## Required parameter
| Parameter | Type | Direction | Description |
| --------- | ---- | --------- | ---------------- |
| `APP_URL` | Text | IN | External API URL |
## Optional parameters
### General
| Parameter | Type | Direction | Description |
| --------------------------- | ------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APP_TIMEOUT` | Numeric | IN | Maximum time interval between sending the request and receiving the response
The default is 30,000 milliseconds (30 seconds) and the maximum is 3,600,000 milliseconds (1 hour); the default can be modified by setting the RestApiClientRequestTimeout parameter value in the web.config file.
✏️ Note: This timeout value must be less than the IIS request timeout value.
|
| `APP_METHOD` | Text | IN | API method
The default is GET. Supports POST, PUT, DELETE, HEAD, PATCH
|
| `APP_REQUEST_CONTENT_TYPE` | Text | IN | Request content type supported by the external API
The application supports application/json and application/x-www-form-urlencoded); the default is application/json.
|
| `APP_RESPONSE_IGNORE_ERROR` | Text | IN | When set to `Y`, the application will ignore the error when a `WebException` occurs or the external API returns a response status equal to or greater than `300`; the default is `N`. |
### `APP_URL` optional parameters
| Parameter | Type | Direction | Description |
| ------------- | ---- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APP_URL_xxx` | Text | IN | API URL optional parameter where xxx is the URL parameter name
It must be defined in the APP\_URL parameter value between brackets (e.g. APP\_URL\_subscriptionId for the URL
|
📌 **Example**
| Parameter | Type | Direction | Value |
| --------------------------- | ---- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APP_URL` | Text | IN | `https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventGrid/topics/{topicName}` |
| `APP_URL_subscriptionId` | Text | IN | `457a2a46-7a7f-4afa-940d-8779e1425fa8` |
| `APP_URL_resourceGroupName` | Text | IN | `dev-group-advantys` |
| `APP_URL_topicName` | Text | IN | `dev-topic` |
The parameters defined above will generate the following URL in `APP_URL`:
```
https://management.azure.com/subscriptions/457a2a46-7a7f-4afa-940d-8779e1425fa8/resourceGroups/dev-group-advantys/providers/Microsoft.EventGrid/topics/dev-topic
```
### Header parameters
| Parameter | Type | Direction | Description |
| ---------------- | ---- | --------- | ------------------------------------------------------------------- |
| `APP_HEADER_xxx` | Text | IN | External API header parameters where `xxx` is the header field name |
#### 📌 Example
| Parameter | Type | Direction | Value |
| -------------------------- | ---- | --------- | --------------------- |
| `APP_HEADER_Authorization` | Text | IN | `Bearer AbCdEf123456` |
| `APP_HEADER_location` | Text | IN | `canadaeast` |
The parameters defined above will generate two headers in the request payload:
```
Authorization: Bearer AbCdEf123456
location: canadaeast
```
### Authorization parameters
The application also supports some predefined authorization header parameters in order to avoid adding these HTTP header parameters with the `APP_HEADER_xxx` parameter name.
| Parameter | Type | Direction | Description |
| ------------------------- | ---- | --------- | --------------------------------------------------------------------------------------- |
| `APP_AUTH_BASIC_USERNAME` | Text | IN | API authorization Basic username |
| `APP_AUTH_BASIC_PASSWORD` | Text | IN | API authorization Basic password; must be used with `APP_AUTH_BASIC_USERNAME` parameter |
| `APP_AUTH_BEARER_TOKEN` | Text | IN | API authorization Bearer token |
| `APP_AUTH_AZ_SAS_TOKEN` | Text | IN | API authorization Azure SAS token |
{% hint style="info" %}
* Only one authorization header can be defined, otherwise an exception is thrown.
* `APP_AUTH_BEARER_TOKEN` is equivalent to defining the header parameter `APP_HEADER_Authorization`.
{% endhint %}
### Request payload
There are two different ways to prepare the request payload. The first way is when you have access to the whole request payload (see [Set the whole request payload via a parameter](#set-the-whole-request-payload-via-a-parameter) below); the second way is by building the JSON or URL encoded payload via IN parameters (see [URL encoded request payload](#url-encoded-request-payload) and [JSON request payload](#json-request-payload) below).
#### Set the whole request payload via a parameter
The following parameters can be used when you have access to the whole request payload, or the request content type is neither `application/json` nor `application/x-www-form-urlencoded`. You can set this request payload in a file/text data or directly in the text value.
| Parameter | Type | Direction | Description |
| -------------------------- | ---- | --------- | ------------------------- |
| `APP_REQUEST_CONTENT_FILE` | File | IN | Request payload in a file |
| `APP_REQUEST_CONTENT` | Text | IN | Request payload |
{% hint style="info" %}
* `APP_REQUEST_CONTENT_FILE` has priority over `APP_REQUEST_CONTENT`.
* `APP_REQUEST_CONTENT` has priority over IN parameters used to build a JSON or an URL encoded payload.
{% endhint %}
#### URL encoded request payload
The following examples show how to build a request payload with `application/x-www-form-urlencoded` as content type.
**Standard URL encoded request payload**
The following parameters are used to build a standard URL encoded request payload:
| Parameter | Type | Direction | Description |
| --------- | ---- | --------- | ----------- |
| `param1` | Text | IN | `value1` |
| `param2` | Text | IN | `value2` |
The parameters defined above will generate the following request payload:
```
param1=value1¶m2=value2
```
**JSON request payload encoded into a key name**
The following parameters are used to build a JSON payload encoded into a key name:
| Parameter | Type | Direction | Description |
| ---------------------------------- | ---- | --------- | ----------- |
| `param1` | Text | IN | `value1` |
| `param2` | Text | IN | `value2` |
| `APP_REQUEST_CONTENT_PAYLOAD_NAME` | Text | IN | `payload` |
The parameters defined above will generate the following request payload:
```
payload: { param1: "value1", "param2": "value2" }
```
{% hint style="info" %}
The `APP_REQUEST_CONTENT_PAYLOAD_NAME` parameter is only supported with the `application/x-www-form-urlencoded` request content type.
{% endhint %}
#### JSON request payload
The following examples show how to build a request payload with `application/json` as content type.
**Standard JSON request payload**
The following parameters are used to build a simple JSON request payload:
| Parameter | Type | Direction | Value |
| ------------------------ | ---- | --------- | ---------------- |
| `person.address.street` | Text | IN | `160 Guy Street` |
| `person.address.zipcode` | Text | IN | `J4G 1U4` |
| `person.age` | Text | IN | `30` |
| `person.name` | Text | IN | `John` |
The parameters defined above will generate the following request payload:
```
{
"person": {
"address": {
"street": "160 Guy Street",
"zipcode": "J4G 1U4"
},
"age": 30,
"name": "John"
}
}
```
If you want to convert this JSON into an array, you have to set the `APP_REQUEST_CONTENT_IS_ARRAY` parameter value to `Y`.
| Parameter | Type | Direction | Description |
| ------------------------------ | ---- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `APP_REQUEST_CONTENT_IS_ARRAY` | Text | IN | When set to Y, the application will convert the JSON request payload into an array; the default is N
Only supported when building JSON request payload with IN parameters.
|
Setting the `APP_REQUEST_CONTENT_IS_ARRAY` parameter to `Y` will generate the following request payload:
```
[{
"person": {
"address": {
"street": "160 Guy Street",
"zipcode": "J4G 1U4"
},
"age": 30,
"name": "John"
}
}]
```
To see how to build more complex JSON, see [Setting a JSON array into a JSON property](#setting-a-json-array-into-a-json-property) and [Setting a JSON object/array into a JSON property using the `__JSON` suffix parameter](#setting-a-json-object-array-into-a-json-property-using-the-__json-suffix-parameter) sections below.
#### **Setting a JSON array into a JSON property**
To set an array into a JSON property, you have to define the property path (e.g. `person.spokenlanguages`) followed by the `__X` suffix, where `X` is the array index number.
The following parameters are used to set a JSON array into a JSON property:
| Parameter | Type | Direction | Value |
| --------------------------- | ---- | --------- | --------- |
| `person.spokenlanguages__0` | Text | IN | `french` |
| `person.spokenlanguages__1` | Text | IN | `english` |
| `person.spokenlanguages__2` | Text | IN | `chinese` |
The parameters defined above will generate the following request payload:
```
{
"person": {
"spokenlanguages": ["french", "english", "chinese"]
}
}
```
If you want to set a JSON array of JSON objects (e.g. `"spokenlanguages": [{"spokenlanguage":"french"}, {"spokenlanguage":"english"}]`) into a JSON property, see the next section.
{% hint style="warning" %}
* The array parameters will be ordered depending on their index number.
* Index numbers have no limit (e.g. `person.spokenlanguages__9999`).
* A correct index sequence is not mandatory (e.g. `person.spokenlanguages__90`, `person.spokenlanguages__30`). The `__30` parameter value will be the first array parameter, and `__90` the second one.
* An exception will be thrown if there is more than one JSON property specified in the IN parameters (e.g. `person.spokenlanguages` and `person.spokenlanguages__0`).
* The `__X` suffix uses **two** underscore characters.
* The parameter value can only be a text value.
{% endhint %}
#### **Setting a JSON object/array into a JSON property using the `__JSON` suffix parameter**
To set a JSON object/array into a JSON property, you have to define the property path (e.g. `person.children`) followed by the `__JSON` suffix with the JSON object/array as the parameter value.
The following parameters are used to set a JSON object/array into a JSON property:
| Parameter | Type | Direction | Value |
| ----------------------- | ---- | --------- | -------------------------------------------- |
| `person.children__JSON` | Text | IN | `[{"name": "child 1"}, {"name": "child 2"}]` |
The parameters defined above will generate the following request payload:
```
{
"person": {
"children": [{
"name": "child 1"
}, {
"name": "child 2"
}]
}
}
```
{% hint style="warning" %}
* An exception will be thrown if there is more than one JSON property specified in the IN parameters. (e.g. `person.children` and `person.children__JSON`).
* The `__JSON` suffix uses **two** underscore characters.
{% endhint %}
### Response payload
The application supports OUT parameters to be mapped with the HTTP response:
| Parameter | Type | Direction | Description |
| ------------------------------- | ------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APP_RESPONSE_STATUS` | Text/Numeric | OUT | Response status code |
| `APP_RESPONSE_CONTENT_TYPE` | Text | OUT | Response content type |
| `APP_RESPONSE_CONTENT_FILE` | File | OUT | Response payload or error message in a file |
| `APP_RESPONSE_CONTENT` | Text | OUT | Response payload or error message |
| `APP_RESPONSE_CONTENT_IS_ARRAY` | Text | OUT | Returns Y if the JSON payload is an array
Only supported for application/json content type responses.
|
#### Mapping a JSON response payload with OUT parameters
The application also supports additional custom OUT parameters to map simple JSON response payloads.
📌 **Example**
JSON response payload:
```
{
"person": {
"address": {
"street": "160 Guy Street",
"zipcode": "J4G 1U4"
},
"age": 30,
"name": "John"
}
}
```
The following parameters allow you to map the response payload into different process data:
| Parameter | Type | Direction | Retrieve the value into a data |
| ------------------------ | ---- | --------- | ------------------------------ |
| `person.address.street` | Text | OUT | `DATA_STREET` |
| `person.address.zipcode` | Text | OUT | `DATA_ZIPCODE` |
| `person.age` | Text | OUT | `DATA_AGE` |
| `person.name` | Text | OUT | `DATA_NAME` |
For mapping complex JSON, see the next section.
#### Mapping a JSON response payload with OUT parameters using JSONPath query language
The application supports the JSONPath query language (similar to XPath expressions in XML). This language allows you to retrieve specific data from a JSON. For more details regarding the JSONPath syntax, see .
📌 **Example**
JSON response payload:
```
{
"person": {
"name": "Elizabeth",
"children": [
{
"name": "Charles",
"age": 30,
"children": [
{
"name": "Nathalie",
"children": [
{
"name": "George",
"age": 8
},
{
"name": "Charlotte",
"age": 10
},
{
"name": "Jefferson",
"age": 7
}
]
},
{
"name": "Harry"
}
]
},
{
"name": "Bob",
"age": 20,
"children": [
{
"name": "John"
},
{
"name": "Mark"
}
]
}
]
}
}
```
For example, here we want to get the names of Charles's grandsons who are older than seven years old, and we also want these names separated by a `|` (using the `APP_JSONPATH_DELIMITER` IN parameter). To get this information, the following parameters must be defined:
| Parameter | Type | Direction | IN Value | OUT Value |
| ------------------------ | ---- | --------- | --------------------------------------------------------------------------------- | -------------------------------------------------- |
| `APP_JSONPATH_DELIMITER` | Text | IN | `\|` | - |
| `PARAM1__JSONPATH` | Text | INOUT | `person.children[?(@.name == 'Charles')].children[*].children[?(@.age > 7)].name` | `DATA1_VALUE` (value will be: `George\|Charlotte`) |
{% hint style="warning" %}
* In the `PARAM1__JSONPATH` parameter name, the `PARAM1` name is not relevant but it must be followed by the `__JSONPATH` suffix (**two** underscores are used in the suffix).
* The default value of `APP_JSONPATH_DELIMITER` is a comma (`,`) when this parameter is not defined.
{% endhint %}
## Usage example with Azure REST API to obtain an OAuth 2.0 access token and then create an Event Grid topic
This example shows how to obtain an access token and use it to create an Event Grid topic. This can be done by creating a process with two actions having RESTAPICLIENT as application. The workflow below illustrates this example:
