REST V2
Learn how to use the REST (V2) component to makes calls to HTTP endpoints. The Documentation Portal provides configuration parameters of this component.
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. This parameter supports Double Braces.
- Headers: configures all the types of headers necessary for the call, that is, Content-Type: application/json or multipart/form-data. This parameter supports Double Braces for both key and value fields.
- Query Params: configures the query parameters necessary for the call. This parameter supports Double Braces.
- Verb: specifies the verb that indicates the HTTP method.
- 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.
- 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. It is important to know that the Retry option is enabled only in case of Server Errors. For other situations, the Retry component must be adopted. To learn more about the Retry component, read this article.
- 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. Its 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.
- Use Dynamic Account: when the option is active, the component will use the account dynamically. When deactivated, it will use the account statically.
- Account Name: account name to be set. The name of the account is generated dynamically via the Store Account component.
- Scoped: when the option is active, the stored account is isolated to other sub-process. In that case, sub-processes will see their own version of the stored account data. This option is not supported for accounts used in headers or body.
Important: 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.
Some of the parameters above support Double Braces. To understand how this language works, read our article by clicking here.
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.
- 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: {}
}
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)
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",
…..
}
}
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 }}
}
}
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
https://www.address.com?access_token=<ACCESS_TOKEN>- GOOGLE_KEY
You can go for this account if it's necessary to use a key for authentication in the Google service.
- 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
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 = requiredAnd 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.
Last modified 1mo ago