REST V2

Discover more about the REST V2 component 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 component. 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.	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.	Content-Type : application/json	Key-value pairs
Query Params (DB)	Configures the query parameters necessary for the call.	N/A	Key-value pairs
Verb	Specifies the HTTP method.	GET	String
Account	Account to be used by the component. Supported accounts: ApiKey, AWS v4, Basic, Certificate Chain, Custom Auth Header, Google Key, Oauth2, and Oauth Bearer Token.	N/A	String
Custom Account #1	Additional account to be used by the component through Double Braces {{ account.custom-1.value }}.	N/A	String
Custom Account #2	Additional account to be used by the component 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).	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 component 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 component.	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 component (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 component

(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

See the accounts supported by REST V2:

• APIKEY

With URL-PARAM-NAME and API-KEY defined in the Basic-type account, the Platform makes the substitution in the call in the following way:

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

• BASIC

With USERNAME and PASSWORD defined in the Basic-type account, the Platform makes the substitution in the call in the following way:

https://www.address.com

HEADERS

Authorization: Basic BASE64(<USERNAME>:<PASSWORD>)

• CUSTOM_AUTH_HEADER

With HEADER-NAME and HEADER-VALUE defined in the CUSTOM_AUTH_HEADER-type account, the Platform makes the substitution in the call in the following way:

https://www.address.com

HEADERS

<HEADER-NAME>: <HEADER-VALUE>

• OAUTH_BEARER_TOKEN

If you already have a OAUTH token, you can save it in this type of account and the Platform makes the substitution in the call in the following way:

https://www.address.com

HEADERS

Authorization: Bearer <TOKEN>

• OAUTH_2

It's specific of each type of supported provider. With this account, the access token is given the way each provider expects.

Microsoft and Google

https://www.address.com

HEADERS

Authorization: Bearer <ACCESS_TOKEN>

Mercado Livre

https://www.address.com?access_token=<ACCESS_TOKEN>

To have an overview about the use of accounts, click here and access our other article.

• GOOGLE_KEY

You can go for this account if it's necessary to use a key for authentication in the Google service.

To have an overview about the use of accounts, access our documentation.

• AWS_4

For you to access some AWS service via REST, it's necessary to use this type of account. With it, the component is responsible for generating the headers of authentication and signing the message. To make it possible, we use the AWS 4 signature.

For DynamoDB, it's necessary to specify the header:

• X-Amz-Target = DynamoDB_20120810.GetItem

If you want to search an item in the database

• X-Amz-Target = DynamoDB_20120810.PutItem

If you want to insert data, access the AWS documentation and know which header to specify in the use of DynamoDB.

For other AWS services it's necessary to check if the header X-Amz-Content-Sha256 is mandatory. In this case, you must inform in the header of the component the “required” value:

X-Amz-Content-Sha256 = required

And if it's necessary to use more than one account type in the same call, get rid of your doubts about Double Braces custom account by clicking here.