IMPORTANT: This documentation has been discontinued. Read the updated REST V2 documentation on our new documentation portal.
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.
Take a look at the configuration parameters of the component:
URL: address that will receive the HTTP call.
Headers: configures all the types of headers necessary for the call (eg.: Content-Type: application/json ou multipart/form-data).
Query Params: configures the query parameters necessary for the call.
Verb: specifies the verb that indicates the HTTP method.
Account: account to be used by the component.
Custom Account #1: additional account to be used by the component through Double Braces {{ account.custom-1.value }}. Click here to read our article about the topic.
Custom Account #2: additional account to be used by the component through Double Braces {{ account.custom-2.value }}. Click here to read our article about the topic.
Connect Timeout: time for the connection expiration (in milliseconds).
Read Timeout: maximum time for the reading (in milliseconds).
Stop On Client Error: if activated, the option interrupts the execution of the pipeline when there's an HTTP error of the 4xx family in the call to the endpoint.
Stop On Server Error: if activated, the option interrupts the execution of the pipeline when there's an HTTP error of the 5xx family in the call to the endpoint.
Advanced Settings: advanced configurations.
Raw Mode: if activated, the option receives or sends a non-JSON payload.
Raw Mode As Base64: when activated, the option shows the response as base64.
Save As Local File: when activated, the option saves the response as a file in the local pipeline directory.
Response File Name: file name of complete file path (eg.: tmp/processed/file.txt). Double Braces are supported.
Allow Insecure Endpoints: when activated, the option allows unsafe calls to HTTPS endpoints to be made.
Enable Retries: when activated, the option allows new tries to be made.
Number Of Retries: maximum number of tries before giving up the call.
Time To Wait Between Retries: maximum time between tries (in milliseconds).
Compress Body With GZIP: when activated, the option allows the body to be compressed with GZIP.
Force HTTP 1.1: when activated, the option forces the request to be executed using HTTP 1.1.
Override Response Charset: when activated, the option will overwrite the charset returned to the endpoint to the charset specified in the “Response Charset” property; otherwise, the return of the charset in the “Content-Type” header will be respected. If no charset in the “Content-Type” header is returned, the UTF-8 standard will be used.
Response Charset: used only when the option “Override Response Charset” is activated, will force the use of the charset specified in the property (Standard: UTF-8).
Disable Connection Pooling: when activated, the option doesn't keep the connections in a pool. Its use is recommended for endpoints that present compatibility issues when connections are reused.
Invalidate SSL Sessions on Every Call: when activated, the option invalidates SSL sessions on every call. It's use is recommended for endpoints that present compatibility issues when SSL sessions are reused (ie.: SSL session resumption). Keep in mind that 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.
IMPORTANT: mind some of the parameters above support Double Braces. To understand how this language works, read our article by clicking here.
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"
}
IMPORTANT: 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: {
},
errorMessage: "This property will be displayed whenever the request return body is not in JSON format. It will contain the conversion error message and the original body of the request return."
}
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": {{ message.fileName }},
"file2": {{ message.fileName2 }}
},
"fields": {
"name": {{ message.name }},
"'address": {{ message.address }}
}
}
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.
Exemple:
{ "field_name1": {{ message.field1}}, "field_name2": {{ message.field2}} }
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:
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:
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:
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
HEADERS
Authorization: Bearer <ACCESS_TOKEN>
Mercado Livre
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, click here and access our other article.
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.
IMPORTANT: 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
Click here to 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.