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 OUT 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 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 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 section.

  • Besides the optional parameters listed below, you can also add additional custom IN and OUT parameters to send/receive custom user-defined data to/from the external API. For more information on and examples of these custom IN and OUT parameters, see the Request payload and Response payload sections.

  • The application supports the JSONPath query language (see 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 section.

  • Application logs are available; these can be specified by setting the RestApiClientLogLevel parameter value in the web.config file to 0 to disable logging, 1 for simple logs, or 2 for debug logs; the default value is 0.

  • 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 greater or equal to 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 https://management.azure.com/subscriptions/{subscriptionId})

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

  • 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.

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 below); the second way is by building the JSON or URL encoded via IN parameters (see URL encoded request payload and 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 not 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

  • 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.

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&param2=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" }

The APP_REQUEST_CONTENT_PAYLOAD_NAME parameter is only supported with the application/x-www-form-urlencoded request content type.

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"
}
}

In case you want convert this JSON into an array, you have to define the APP_REQUEST_CONTENT_IS_ARRAY parameter value as 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.

The APP_REQUEST_CONTENT_IS_ARRAY parameter set 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 and 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"]
}
}

In case 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.

  • 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.

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 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"
}]
}
}
  • 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.

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 supports also additional custom OUT parameters to map simple JSON response payload.

Example:

JSON response payload:

{
"person": {
"address": {
"street": "160 Guy Street",
"zipcode": "J4G 1U4"
},
"age": 30,
"name": "John"
}
}

The following parameters will allow to map the response payload in 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 https://github.com/json-path/JsonPath.

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)

  • 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.

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:

The next sections describe the parameters that must be declared for each action.

GET_TOKEN action: Obtaining an OAuth 2.0 access token

The following parameters are needed to get an access token to use the Azure Resource management API. This token will be stored in the access_token OUT parameter and will be used when creating an Event Grid topic in the next section.

Parameter

Type

Direction

Value

APP_URL

Text

IN

https://login.microsoftonline.com/{tenandId}/oauth2/token

APP_URL_tenantId

Text

IN

a6e70c61-fabd-4885-89f7-97121e92db7f

APP_METHOD

Text

IN

POST

APP_REQUEST_CONTENT_TYPE

Text

IN

application/x-www-form-urlencoded

grant_type

Text

IN

client_credentials

client_id

Text

IN

b7e29e2f-6e2b-4375-9684-8151431d4ca6

client_secret

Text

IN

lxy/IwKyTedHUWMeeUtyCtu7/YUy0rNGoY3NNWXXotI=

resource

Text

IN

https://management.core.windows.net/

access_token

Text

OUT

DATA_ACCESS_TOKEN

The parameters defined above will generate the following request payload:

POST https://login.microsoftonline.com/a6e70c61-fabd-4885-89f7-97121e92db7f/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=b7e29e2f-6e2b-4375-9684-8151431d4ca6&client_secret=lxy/IwKyTedHUWMeeUtyCtu7/YUy0rNGoY3NNWXXotI=&resource=https://management.core.windows.net/

Here's the response from the Azure API:

{
"token_type":"Bearer",
"expires_in":"3600",
"ext_expires_in":"3600",
"expires_on":"1555951493",
"not_before":"1555947593",
"resource":"https://management.core.windows.net/",
"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d..."
}

The access_token OUT parameter is mapped with the access_token JSON property.

For more details about how to get an access token to use the Azure Resource API, see https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-oauth2-client-creds-grant-flow#request-an-access-token.

CREATE_TOPIC action: Creating an Event Grid topic

The following parameters are needed to create an Event Grid topic using the Azure Resource management API.

Parameter

Type

Direction

Value

APP_URL

Text

IN

https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventGrid/topics/{topicName}?api-version={api-version}

APP_URL_subscriptionId

Text

IN

235765d9-5d62-43f4-a730-2ed71a3f8adb

APP_URL_resourceGroupName

Text

IN

dev-group-advantys

APP_URL_topicName

Text

IN

new-topic-example

APP_URL_api-version

Text

IN

2018-09-15-preview

APP_METHOD

Text

IN

PUT

APP_REQUEST_CONTENT_TYPE

Text

IN

application/json

APP_AUTH_BEARER_TOKEN

Text

IN

DATA_ACCESS_TOKEN

location

Text

IN

canadaeast

The parameters defined above will generate the following request payload:

PUT https://management.azure.com/subscriptions/235765d9-5d62-43f4-a730-2ed71a3f8adb/resourceGroups/dev-group-advantys/providers/Microsoft.EventGrid/topics/new-topic-example?api-version=2018-09-15-preview
Host: management.azure.com
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1d...
location: canadaeast

Here's the response from the Azure API:

{
"properties":{
"provisioningState":"Creating",
"endpoint":null
},
"location":"canadaeast",
"tags":null,
"id":"/subscriptions/994e2fc0-937d-4110-b355-e7473acef822/resourceGroups/dev-evt-grid/providers/Microsoft.EventGrid/topics/test-from-wfg",
"name":"test-from-wfg",
"type":"Microsoft.EventGrid/topics"
}

For more information about how to create an Event Grid topic and the Azure REST API, see https://docs.microsoft.com/en-us/rest/api/eventgrid/topics/createorupdate.

Enabling SSL/TLS

In case of a Could not create SSL/TLS secure channel error, strong encryption must be enabled by executing the following code in PowerShell:

Set-ItemProperty -Path 'HKLM:\SOFTWARE\Wow6432Node\Microsoft\.NetFramework\v4.0.30319' -Name 'SchUseStrongCrypto' -Value '1' -Type DWord
Set-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\.NetFramework\v4.0.30319' -Name 'SchUseStrongCrypto' -Value '1' -Type DWord