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.	0	Integer
Time To Wait Between Retries	Maximum time between tries (in milliseconds).	0	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.