REST V2

Discover more about the REST V2 connector and how to use it on the Digibee Integration Platform.

REST V2 makes calls to HTTP endpoints, turning actions as GET, POST, PUT and DELETE much simpler.

The main difference to the V1 is the use of Double Braces expressions to compose URL, headers, query parameters and body of the message, allowing direct access to the pipeline data.

Parameters

Take a look at the configuration options for the connector. Parameters supported by Double Braces expressions are marked with (DB).

Parameter

Description

Default value

Data type

URL (DB)

Address that will receive the HTTP call. This parameter supports Double Braces, but the reference to account information is not allowed.

https://viacep.com.br/ws/{{ DEFAULT(message.$.cep, "04547-130") }}/json/

String

Headers (DB)

Configures all types of headers necessary for the call (for example, Content-Type: application/json or multipart/form-data). This parameter supports Double Braces for both Key and Value fields. However, the reference to account information is only allowed for Value fields.

Content-Type : application/json

Key-value pairs

Query Params (DB)

Configures the query parameters necessary for the call. This parameter only supports Double Braces for Value fields.

N/A

Key-value pairs

Verb

Specifies the HTTP method.

GET

String

Account

Account to be used by the connector. Supported accounts: API Key, AWS V4, Basic, Certificate Chain, Custom Auth Header, Google Key, OAuth2, OAuth Bearer Token, and NTLM.

N/A

String

Custom Account #1

Additional account to be used by the connector through Double Braces {{ account.custom-1.value }}.

N/A

String

Custom Account #2

Additional account to be used by the connector through Double Braces {{ account.custom-2.value }}.

N/A

String

Connect Timeout

Time for the connection expiration (in milliseconds).

30000

Integer

Read Timeout

Maximum time for reading (in milliseconds).

30000

Integer

Stop On Client Error

If activated, interrupts the execution of the pipeline on a 4xx HTTP error.

False

Boolean

Stop On Server Error

If activated, interrupts the execution of the pipeline on a 5xx HTTP error.

False

Boolean

Advanced Settings

Advanced configurations.

False

Boolean

Raw Mode

If activated, receives or sends a non-JSON payload.

False

Boolean

Raw Mode As Base64

When activated, shows the response as base64.

False

Boolean

Save As Local File

When activated, saves the response as a file in the local pipeline directory.

False

Boolean

Response File Name (DB)

File name or complete file path (for example, tmp/processed/file.txt). This parameter supports Double Braces, but the reference to account information is not allowed.

N/A

String

Allow Insecure Endpoints

When activated, allows unsafe calls to HTTPS endpoints to be made.

False

Boolean

Enable Retries

When activated, allows new tries in case of server errors.

False

Boolean

Number Of Retries

Maximum number of tries before giving up the call.

Integer

Time To Wait Between Retries

Maximum time between tries (in milliseconds).

Integer

Compress Body With GZIP

When activated, allows the body to be compressed with GZIP.

False

Boolean

Force HTTP 1.1

When activated, forces the request to use HTTP 1.1.

False

Boolean

Override Response Charset

When activated, overwrites the charset returned to the endpoint with the specified charset in "Response Charset" property. Otherwise, the return of the charset in the “Content-Type” header will be respected.

False

Boolean

Response Charset

Used only when "Override Response Charset" is activated; forces the use of the specified charset (Standard: UTF-8).

UTF-8

String

Disable Connection Pooling

When activated, doesn't keep connections in a pool. Recommended for endpoints with connection reuse issues.

False

Boolean

Invalidate SSL Sessions on Every Call

When activated, invalidates SSL sessions on every call. Recommended for endpoints with SSL session reuse issues. Activating the option will make the connector single-threaded - it means that every execution will be sequential for the same REST added to the pipeline canvas.

False

Boolean

Use Dynamic Account

When active, uses the account dynamically; when inactive, uses the account statically.

False

Boolean

Account Name

Account name to be set, generated dynamically via the Store Account connector.

N/A

String

Scoped

When activated, the stored account is isolated to other sub-processes. Not supported for accounts used in headers or body. To know more about the Scoped flag, check out the Dynamic Accounts documentation.

False

Boolean

Currently, the Use Dynamic Account, Account Name and Scoped parameters can only be used in Pipeline Engine v2 and are only available in the Restricted Beta phase. To learn more about it, read the article Beta program.

Messages flow

Input

You can use the following configuration in the body of the message and also use Double Braces:

{
    "id": {{ DEFAULT(message.customer.id, UUID()) }},
    "name": {{ message.customer.name }},
    "type": "1"
}

It doesn't apply to the verb GET.

Output

in case of success

{
    status: 2xx,
    statusMessage: "STATUS_MESSAGE",
    body: {},
    headers: {}
}

in case of success (using the "Raw Mode As Base64" flag)

{
    status: 2xx,
    statusMessage: "STATUS_MESSAGE",
    body: "content in base64 format",
    headers: {}
}

in case of success (using the “Save As Local File” flag)

{
    status: 2xx,
    statusMessage: "STATUS_MESSAGE",
    body: {
        file: "name of the file defined in the Response File Name property"
    },
    headers: {}
}

in case of error

{
    error: "error message",
    code: XXX,
    body: {},
    headers: {}
}

REST V2 in Action

Sending a binary file

To send a binary file through REST V2, all you have to do is inform:

the destination endpoint
the content type (MIME Type of the file) in the header (eg.: application/pdf)
the path where the file can be found (show it in the File Name field)

How to make requests by using content-type: MultiPart/form-data

The first thing you have to do is to specify this header in the connector (Content-Type: Multipart/form-data).

After that, when selecting any HTTP verb (except to GET), a field will be opened for you to specify the head of the payload to be sent. This must be the standard to:

specify fields

{
"fields": {
     "field_name1": "field_value_1",
     "field_name2": "field_value_2",
     …….
    }
}

specify files

{"files": {"file_field_name1": "path_where_the_file_is_found1","file_field_name2": "path_where_the_file_is_found2",…..}}

If you need to use both specifications, you can combine them with Double Braces expressions:

{
    "files": {
        "file_field_name1": "path_where_the_file_is_found1",
        "file_field_name2": "path_where_the_file_is_found2",
        …..
    }
}

How to make requests by using content-type: application/x-www-form-urlencoded

The first thing you have to do is to specify this header in the connector

(Content-Type: application/x-www-form-urlencoded).

After that, when selecting any HTTP verb (except to GET), a field will be opened for you to specify the head of the payload to be sent.

Example:

{
    "files": {
        "file": {{ message.fileName }},
        "file2": {{ message.fileName2 }}
    },
    "fields": {
        "name": {{ message.name }},
        "'address": {{ message.address }}
    }
}

Using accounts

In REST V2, you can configure three types of account parameters:

Account
Custom Account #1
Custom Account #2

The difference between the parameters is that if you set the Account parameter, the connector will automatically prepare the request with the account information, according to the authentication technology. However, if you configure one or more Custom Accounts, they can only be used to reference their information in other fields through Double Braces.

The Account parameter always takes precedence over Custom Accounts.

These are the supported account types in REST V2:

API Key
AWS V4
Basic
Certificate Chain
Custom Auth Header
Google Key
OAuth2
OAuth Bearer Token
NTLM

Learn more about how the REST V2 prepares the authorization depending on the account type:

API Key

With the URL-PARAM-NAME and API-KEY values defined in the API Key account type, the Platform adds a new set of query parameters and values in the request as follows:

https://www.address.com?<URL-PARAM-NAME>=<API-KEY>

AWS V4

If you need to access an AWS service through a REST API call, it’s necessary to use this type of account. Internally, the platform generates the AWS authentication headers and signs the message with the AWS 4 signature.

Check the documentation of the AWS service you want to access to see which additional headers or parameters need to be set up for the REST API call.

Basic

If USERNAME and PASSWORD are defined in the Basic account type, the Platform encodes the data in BASE64 format and adds an authorization header to the request as follows:

Authorization: Basic <ENCODED-INFORMATION>

Certificate Chain

When this type of account is set, the Platform uses the CHAIN to validate and establish a secure connection with the API server.

Custom Auth Header

With HEADER-NAME and HEADER-VALUE defined in the Custom Auth Header account type, the Platform creates a custom header and inserts it into the request as follows:

<HEADER-NAME>: <HEADER-VALUE>

Google Key

If you need to access a Google service through a REST API call, it's necessary to use this type of account. Internally, the platform generates the Google Authentication Token and inserts it into an authentication header as follows:

Authorization: Bearer <GOOGLE-JWT-TOKEN>

Check the documentation of the Google service you want to access to see which additional headers or parameters need to be set up for the REST API call.

OAuth 2

This type of account triggers different behaviors depending on what the respective provider expects. Here's how the Platform handles OAuth 2 authentication with the providers Digibee supports:

Microsoft and Google: for these providers, the Platform generates the access token and inserts it into an authorization header as follows: Authorization: Bearer <PROVIDER_ACCESS_TOKEN>
Mercado Livre: for this provider, the Platform generates the access token and inserts it as the value of a query parameter in the request, as follows: https://www.address.com?access_token=<API-KEY>

OAuth Bearer Token

If you already have an OAuth token, you can store it in this type of account and the Platform will create it as follows and replace it in an Authorization header:

Authorization: Bearer <TOKEN>

Further information can be found in the Accounts documentation.

PreviousEmail V1: Usage example (Deprecated)NextREST V1 (Deprecated)

Last updated 1 month ago