# REST V2

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

{% hint style="info" %}
This connector supports AI-assisted configuration. [Learn more](https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/development-cycle/build-overview/canvas/connector-ai-assistant).
{% endhint %}

## Parameters

Take a look at the configuration options for the connector. Parameters supported by [Double Braces expressions](https://docs.digibee.com/documentation/connectors-and-triggers/double-braces/overview) are marked with `(DB)`. 

### **Section Rest Connector V2 tab**

<table data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Default value</th><th>Data type</th></tr></thead><tbody><tr><td><strong>URL</strong> <code>(DB)</code></td><td>Address that will receive the HTTP call. This parameter supports Double Braces, but the reference to account information is not allowed.</td><td><a href="https://viacep.com.br/ws/%7B%7B"><code>https://viacep.com.br/ws/{{</code></a> <code>DEFAULT(message.$.cep, "04547-130") }}/json/</code></td><td>String</td></tr><tr><td><strong>Headers</strong> <code>(DB)</code></td><td>Configures all types of headers necessary for the call (for example, <code>Content-Type: application/json</code> or <code>multipart/form-data</code>). This parameter supports Double Braces for both key and value fields. However, the reference to account information is only allowed for Value fields.</td><td><code>Content-Type : application/json</code></td><td>Key-value pairs</td></tr><tr><td><strong>Query Params</strong> <code>(DB)</code></td><td>Configures the query parameters necessary for the call. This parameter only supports Double Braces for Value fields.</td><td>N/A</td><td>Key-value pairs</td></tr><tr><td><strong>Verb</strong></td><td>Specifies the HTTP method.</td><td>GET</td><td>String</td></tr><tr><td><strong>Use Dynamic Account</strong></td><td>When active, uses the account dynamically; when inactive, uses the account statically.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Account Name</strong></td><td>Account name to be set, generated dynamically via the <a href="../tools/store-account"><strong>Store Account</strong></a> connector. It is only available if the <strong>Use Dynamic Account</strong> parameter is <strong>active</strong>.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Scoped</strong></td><td>When activated, the stored account is isolated to other sub-processes. Not supported for accounts used in headers or body. It is only available if the <strong>Use Dynamic Account</strong> parameter is <strong>active</strong>. To know more about the Scoped flag, check out the <a href="https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/development-cycle/overview/runtime/pipeline-engine/dynamic-accounts">Dynamic Accounts documentation</a>.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Account</strong></td><td>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. It is only available if the <strong>Use Dynamic Account</strong> parameter is <strong>inactive</strong>.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Custom Account #1</strong></td><td>Additional account to be used by the connector through Double Braces <code>{{ account.custom-1.value }}</code></td><td>N/A</td><td>String</td></tr><tr><td><strong>Custom Account #2</strong></td><td>Additional account to be used by the connector through Double Braces <code>{{ account.custom-2.value }}</code></td><td>N/A</td><td>String</td></tr><tr><td><strong>Connect Timeout</strong></td><td>Maximum time to establish a connection with the server. Starts counting when attempting to connect (DNS + TCP handshake + TLS, if applicable). <a href="#configuring-the-timeouts">Learn more</a>.</td><td>30000</td><td>Integer</td></tr><tr><td><strong>Read Timeout</strong></td><td>Maximum wait time to read data from the server (after the connection is established). Starts counting after the request is sent, while waiting for the response. <a href="#configuring-the-timeouts">Learn more</a>.</td><td>30000</td><td>Integer</td></tr><tr><td><strong>Write Timeout</strong></td><td>Maximum time to send request data to the server, in milliseconds. Starts counting during the sending of the request body. <a href="#configuring-the-timeouts">Learn more</a>.</td><td>30000</td><td>Integer</td></tr><tr><td><strong>Call Timeout</strong></td><td>Total allowed time for the entire request (connect, write, read), in milliseconds. Starts counting from the beginning of the HTTP call until it ends. <a href="#configuring-the-timeouts">Learn more</a>.</td><td>30000</td><td>Integer</td></tr><tr><td><strong>Stop On Client Error</strong></td><td>If activated, interrupts the execution of the pipeline on a 4xx HTTP error.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Stop On Server Error</strong></td><td>If activated, interrupts the execution of the pipeline on a 5xx HTTP error.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Advanced Settings</strong></td><td>Advanced configurations.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Raw Mode</strong></td><td>If activated, receives or sends a non-JSON payload.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Raw Mode As Base64</strong></td><td>When activated, shows the response as base64.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Save As Local File</strong></td><td>When activated, saves the response as a file in the local pipeline directory.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Response File Name</strong> <code>(DB)</code></td><td>File name or complete file path (for example, <code>tmp/processed/file.txt)</code>. This parameter supports Double Braces, but the reference to account information is not allowed.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Allow Insecure Endpoints</strong></td><td>When activated, allows unsafe calls to HTTPS endpoints to be made.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Enable Retries</strong></td><td>When activated, allows new tries in case of server errors.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Number Of Retries</strong></td><td>Maximum number of tries before giving up the call.</td><td>0</td><td>Integer</td></tr><tr><td><strong>Time To Wait Between Retries</strong></td><td>Maximum time between tries (in milliseconds).</td><td>0</td><td>Integer</td></tr><tr><td><strong>Compress Body With GZIP</strong></td><td>When activated, allows the body to be compressed with GZIP.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Force HTTP 1.1</strong></td><td>When activated, forces the request to use HTTP 1.1.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Override Response Charset</strong></td><td>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.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Response Charset</strong></td><td>Used only when "Override Response Charset" is activated; forces the use of the specified charset (Standard: UTF-8).</td><td>UTF-8</td><td>String</td></tr><tr><td><strong>Disable Connection Pooling</strong></td><td>When activated, doesn't keep connections in a pool. Recommended for endpoints with connection reuse issues.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Invalidate SSL Sessions on Every Call</strong></td><td>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.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Enable Follow Redirect</strong></td><td>When enabled, the pipeline execution will automatically follow redirects for 302 responses. Otherwise, it will return the original 302 response, allowing data inspection before the redirect is followed.</td><td>True</td><td>Boolean</td></tr></tbody></table>

{% hint style="info" %}
Currently, the **Use Dynamic Account**, **Account Name** and **Scoped** parameters can only be used in Pipeline Engine v2.
{% endhint %}

### **Documentation tab**

<table data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Default value</th><th>Data type</th></tr></thead><tbody><tr><td><strong>Documentation</strong></td><td>Section for documenting any necessary information about the connector configuration and business rules.</td><td>N/A</td><td>String</td></tr></tbody></table>

## Messages flow <a href="#messages-flow" id="messages-flow"></a>

### Input <a href="#input" id="input"></a>

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

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

{% hint style="warning" %}
It doesn't apply to the verb GET.
{% endhint %}

### Output <a href="#output" id="output"></a>

* **in case of success**

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

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

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

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

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

* **in case of error**

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

## REST V2 in Action <a href="#rest-v2-in-action" id="rest-v2-in-action"></a>

### **Configuring the timeouts**

#### **Connect Timeout**

Defines the maximum time allowed to establish a connection with the server.

If the server is slow to accept the connection or unavailable, the request fails after this timeout.

**Example:** The server takes longer than 10 seconds to complete the handshake. The connection fails due to a timeout.

#### **Read Timeout**

Specifies the maximum time to wait for a response after the request has been sent.

Prevents the client from hanging indefinitely while waiting for data.

**Example:** The server accepted the connection but takes more than 15 seconds to start responding. A timeout error is returned.

#### **Write Timeout**

Sets the maximum time allowed to send the request body to the server.

Particularly relevant for requests with large payloads (for example, file uploads).

**Example:** Uploading a file takes more than 30 seconds. The request fails due to a write timeout.

#### **Call Timeout**

Defines the total timeout for the entire HTTP call, including connection, writing, and reading.

If the combined duration exceeds this value, the request is aborted.

**Example:** You configure a 60-second timeout for the entire operation. If connecting, sending, and receiving together exceed this limit, the request is canceled.

### Sending a binary file <a href="#sending-a-binary-file" id="sending-a-binary-file"></a>

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)

### Making requests using content-type: MultiPart/form-data <a href="#how-to-make-requests-by-using-content-type-multipartform-data" id="how-to-make-requests-by-using-content-type-multipartform-data"></a>

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**

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

* **specify files**

```json
{
  "files": {
    "file_field_name1": "path_where_the_file_is_found1",
    "file_field_name2": "path_where_the_file_is_found2",
    "file_field_name3": "path_where_the_file_is_found3",
    ...
  }
}
```

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

```json
{
    "files": {
        "file_field_name1": "path_where_the_file_is_found1",
        "file_field_name2": "path_where_the_file_is_found2",
        ...
    }
}
```

### Making requests using content-type: **application/x-www-form-urlencoded** <a href="#h_0fa1297eb7" id="h_0fa1297eb7"></a>

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:

```json
{
  "field_name1": "field_value_1",
  "field_name2": "field_value_2",
  ...
}

```

### Using accounts <a href="#using-accounts" id="using-accounts"></a>

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.

{% hint style="info" %}
The **Account** parameter always takes precedence over **Custom Accounts**.
{% endhint %}

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.

{% hint style="info" %}
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.
{% endhint %}

#### 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>
```

{% hint style="info" %}
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.
{% endhint %}

#### 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 &lt;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=&lt;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](https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/platform-administration/settings/accounts).