Skip to main content
Version: ACE 5

REST HTTP

Overview

REST HTTP step allows making network requests to query or send data.

Response Type:

In order to deal with different response types, the Rest HTTP step allows to chose the expected format of the response. The values can be either body, text or file (the default value is body).

  • The body option will return the response body as successfully parsed JSON.
  • The text option will return the response body as text, even if the value is not valid (based on the Content-Type).
  • The file option will cause the response to be downloaded as a file. The target path will be populated with a file reference.

The file reference generated when file is selected is an object containing the following properties:

  • id - file reference id
  • fileName - file name (locked as ace-download)
  • extension - file extension (inferred from content type)
  • contentType - the content type received in the response

OAuth 2.0

Rest HTTP step has OAuth 2.0 advanced authentication option, and when selected, the step first performs authentication against some authentication server, and then adds the generated token to the request.

In order to perform such authentication you should also provide:

  • Access Token URL (required) - the endpoint for authentication server.
  • Client ID (required) - the client identifier issued to the client during the Application registration process.
  • Client Secret (required) - the client secret issued to the client during the Application registration process.
  • Scope(optional) - the scope of the access request.

It is advised to define the data above as environment variables, and to make sure that these environment variables are defined eventually in your deployment.

AWS Signature

Rest HTTP step has AWS Signature advanced authentication option, and when selected, the step generates advanced authorization headers to connect to AWS services.

In order to perform such authentication you should also provide:

  • Access Key (required) - Identifies the AWS account or IAM user making the request.
  • Secret Key (required) - Used to sign the request for authentication.
  • AWS Region (required) - Specifies the AWS data center to interact with (e.g., us-east-1).
  • Service Name (required) - Indicates the AWS service the request is for (e.g., s3, ec2).
  • Session Token (optional) - Temporary credential for secure access with temporary roles or sessions.

It is advised to define the data above as environment variables, and to make sure that these environment variables are defined eventually in your deployment.

mTLS

Rest HTTP step has mTLS checkbox and when checked mTLS(mutual authentication) will be used between requests.

In order to perform such authentication, along with checking the mTLS checkbox, you need to also provide:

  • mTLS certificate (required) - certificate used for authorization.
  • mTLS key (required) - private key.

mTLS certificate and mTLS private key are expected to be in PEM format. Certificate should not be password protected. OpenSSL can be used to generate PEM files from other formats such as P12/x509.

It is advised to define the data above as environment variables, and to make sure that these environment variables are defined eventually in your deployment.

Timeouts

Rest HTTP step has a Response Timeout and a Deadline Timeout fields.

Response Timeout - The amount of time in milliseconds for the request to start responding. Default cross all Rest HTTP steps is 10,000, which is set by the deployment’s environment variable RESPONSE_TIMEOUT.

Deadline Timeout - The amount of time in milliseconds for the request to finish its response. Default cross all Rest HTTP steps is 60,000, which is set by the deployment’s environment variable DEADLINE_TIMEOUT.

Inside a step, can be specified in milliseconds (e.g. 20000), or by the value of a predefined workspace variable ( e.g. {{$env.RESPONSE_TIMEOUT}}, {{$env.DEADLINE_TIMEOUT}}). If specified in a step, the step’s timeout overrides the deployment’s corresponding timeout.

Base 64 file upload

It is possible to upload files using Rest HTTP Step by passing Base64 string to step. User needs to select Base64 file from dropdown in the step, then user needs to provide base64 string to step. This can be done by passing it from doc object using mustache syntax {{base64}}. User can also provide optional string value for Field Name witch by default is file and optional string value for File Name. These values are optional and it depends on backend endpoint if they should be passed to step. (example for different optional values: fieldName: "image", fileName: "image.png")

Binary file upload

It is possible to upload file directly using Rest HTTP Step by passing file reference string to step. User needs to select Binary from dropdown in the step, then user needs to provide file reference string to step.

Form data upload

It is possible to upload multipart/form-data using Rest HTTP Step by passing form data to step. User needs to select Form data as the body to send in the rest request. This enables two input fields, one for Text fields and one for File fields.

info

See tutorial uploading form files to backend service for an end to end example.

Text fields

Using the Text fields input, it is possible to define the text fields that will be sent as part of the multipart/form-data form.

File fields

Using the File fields input, it is possible to define the file fields that will be sent as part of the multipart/form-data form. It is possible to send one or many files under the same fieldname.

File fields input
{
"myFieldName": {
"id": "sample file reference"
},
"myFieldWithManyFiles": [
{
"id": "sample file reference nr. 1"
},
{
"id": "sample file reference nr. 2"
}
]
}

This will upload one file in the field myFieldName, and an array of files in the field myFieldWithManyFiles.

Rest HTTP Step multipart/form-data file upload also enables setting a custom contentType and fileName for the specified file. This can be achieved by modifying the previous example to also define a contentType and fileName in the respective file object.

File fields input
{
"myFieldName": {
"id": "example pointer to the referenced file",
"fileName": "ace-upload.yaml",
"contentType": "application/json"
}
}

Configuration

Url

Request url for the REST service.

Method

The REST method type (Default is GET).

Target path

Define the path in which to store the result returned when executing the api.

Path to store headers

Define the path in which to store request/response headers of the api call. No header values will be stored if left blank.

Store target path results in cache

If checked will enable caching response values.

Disable Headers key for caching

Disable the usage of the HTTP headers in the cache key of the results

Cache Key

if specified, will be used as key to store the cached response.

Cache clean-up condition

If condition is true, then step cache is cleared, else if condition is false or not defined, then step behaves as usually.

TTL

Time in minutes for how long to keep the cached results.

Request start timeout

The amount of time in milliseconds for the request to start responding(Default 10,000).

Request finish timeout

The amount of time in milliseconds for the request to finish its response(Default 60,000).

Query Params

The query params to send in the REST request.

HTTP Headers

Http headers to send in the REST request.

Request body

JSON object, XML String, Text, Base64 String, Form data, Form URL encoded or Binary - Data to be sent with the request.

If content-type header is not set in headers then selecting JSON, XML, TEXT, Form data or Form URL encoded will set content-type in headers as application/json, application/xml, text/plain, multipart/form-data, application/x-www-form-urlencoded respectively.

Field Name

Optional parameter for Base64 file upload (default is file).

File Name

Optional parameter for Base64 file upload (example: pdfFile.pdf).

Response object format

The expected format of the response. Body converts response to object. Text is plain text response. File is converted to file reference.

Append errors to context?

If enabled, then adds errors to doc context in errorContext variable instead of throwing an error.

Don't follow redirects

If enabled, then request will not follow redirects in such cases when response returns HTTP code like 303.

Examples

GET

Step Configuration
name: Step rest-new
description: ""
config:
endpoint:
url: "https://60927f7f85ff510017212f24.mockapi.io/users"
restRequest: JSON
expectedResponseLocation: body
targetPath: result
headerPath: headers
headers: {}
oAuthConfig: {}
json: {}
disableHeadersInKey: false
stepType: rest-new
condition: ""
Flow Result
{
"doc": {
"headers": {
"request": {
"content-type": "application/json"
},
"response": {
"server": "Cowboy",
"report-to": "{\"group\":\"heroku-nel\",\"max_age\":3600,\"endpoints\":[{\"url\":\"https://nel.heroku.com/reports?ts=1733748527&sid=1b10b0ff-8a76-4548-befa-353fc6c6c045&s=0NjzsgykWRKnklZH5Ae2wCf9DE6x0chpqOxzo7GMZT8%3D\"}]}",
"reporting-endpoints": "heroku-nel=https://nel.heroku.com/reports?ts=1733748527&sid=1b10b0ff-8a76-4548-befa-353fc6c6c045&s=0NjzsgykWRKnklZH5Ae2wCf9DE6x0chpqOxzo7GMZT8%3D",
"nel": "{\"report_to\":\"heroku-nel\",\"max_age\":3600,\"success_fraction\":0.005,\"failure_fraction\":0.05,\"response_headers\":[\"Via\"]}",
"connection": "close",
"x-powered-by": "Express",
"access-control-allow-origin": "*",
"access-control-allow-methods": "GET,PUT,POST,DELETE,OPTIONS",
"access-control-allow-headers": "X-Requested-With,Content-Type,Cache-Control,access_token",
"content-type": "application/json",
"content-length": "5607",
"etag": "\"-451939666\"",
"date": "Mon, 09 Dec 2024 12:48:47 GMT",
"via": "1.1 vegur"
},
"status": 200
},
"result": [
{
"createdAt": "2021-10-10T13:13:14.241Z",
"name": "Melba Leffler",
"avatar": "https://cdn.fakercloud.com/avatars/iamsteffen_128.jpg",
"id": "1"
},
{
"createdAt": "2021-10-09T16:05:49.244Z",
"name": "Omar Waters",
"avatar": "https://cdn.fakercloud.com/avatars/ovall_128.jpg",
"id": "2"
},
{
"createdAt": "2021-10-10T13:59:40.839Z",
"name": "Pauline Zulauf",
"avatar": "https://cdn.fakercloud.com/avatars/moscoz_128.jpg",
"id": "3"
},
{
"createdAt": "2021-10-10T12:58:02.333Z",
"name": "John Doe",
"avatar": "https://cdn.fakercloud.com/avatars/konus_128.jpg",
"id": "4"
}
]
},
"errors": [],
"performance": {
"steps": [
{
"step": "Step rest-new",
"executionTime": 313
}
],
"executionTimeOfFlow": 313,
"timeMetric": "ms"
},
"files": [
{
"targetProperty": "result",
"files": []
}
]
}

GET (with errors)

Step Configuration
name: Step rest-new
description: ""
config:
endpoint:
url: https://reqres.in/api/unknown/23
restRequest: JSON
expectedResponseLocation: body
targetPath: result
headers: {}
oAuthConfig: {}
json: {}
disableHeadersInKey: false
stepType: rest-new
condition: ""
Flow Result
{
"doc": {},
"errors": [
{
"error": "Error in flow 'newFlow824039' : REST: {} ResponseCode: 404",
"body": {
"request": {},
"response": {}
},
"headers": {
"request": {
"content-type": "application/json"
},
"response": {
"date": "Mon, 09 Dec 2024 13:01:10 GMT",
"content-type": "application/json; charset=utf-8",
"content-length": "2",
"connection": "close",
"report-to": "{\"group\":\"heroku-nel\",\"max_age\":3600,\"endpoints\":[{\"url\":\"https://nel.heroku.com/reports?ts=1733749270&sid=c4c9725f-1ab0-44d8-820f-430df2718e11&s=cGQ8VqK11bZH%2FbGcJBJzlDxJDqfEO413XcIycoLodFs%3D\"}]}",
"reporting-endpoints": "heroku-nel=https://nel.heroku.com/reports?ts=1733749270&sid=c4c9725f-1ab0-44d8-820f-430df2718e11&s=cGQ8VqK11bZH%2FbGcJBJzlDxJDqfEO413XcIycoLodFs%3D",
"nel": "{\"report_to\":\"heroku-nel\",\"max_age\":3600,\"success_fraction\":0.005,\"failure_fraction\":0.05,\"response_headers\":[\"Via\"]}",
"x-powered-by": "Express",
"access-control-allow-origin": "*",
"etag": "W/\"2-vyGp6PvFo4RvsFtPoIWeCReyIC8\"",
"via": "1.1 vegur",
"cache-control": "max-age=14400",
"cf-cache-status": "EXPIRED",
"vary": "Accept-Encoding",
"server": "cloudflare",
"cf-ray": "8ef52eac9d99be0c-DUB",
"server-timing": "cfL4;desc=\"?proto=TCP&rtt=1656&min_rtt=1516&rtt_var=668&sent=3&recv=5&lost=0&retrans=0&sent_bytes=2819&recv_bytes=622&delivery_rate=1883905&cwnd=251&unsent_bytes=0&cid=60b413e67942d5e6&ts=33&x=0\""
},
"status": 404
},
"statusCode": 404
}
],
"performance": {
"steps": [
{
"step": "Step rest-new",
"executionTime": 98
}
],
"executionTimeOfFlow": 98,
"timeMetric": "ms"
},
"headers": {
"request": {
"content-type": "application/json"
},
"response": {
"date": "Mon, 09 Dec 2024 13:01:10 GMT",
"content-type": "application/json; charset=utf-8",
"content-length": "2",
"connection": "close",
"report-to": "{\"group\":\"heroku-nel\",\"max_age\":3600,\"endpoints\":[{\"url\":\"https://nel.heroku.com/reports?ts=1733749270&sid=c4c9725f-1ab0-44d8-820f-430df2718e11&s=cGQ8VqK11bZH%2FbGcJBJzlDxJDqfEO413XcIycoLodFs%3D\"}]}",
"reporting-endpoints": "heroku-nel=https://nel.heroku.com/reports?ts=1733749270&sid=c4c9725f-1ab0-44d8-820f-430df2718e11&s=cGQ8VqK11bZH%2FbGcJBJzlDxJDqfEO413XcIycoLodFs%3D",
"nel": "{\"report_to\":\"heroku-nel\",\"max_age\":3600,\"success_fraction\":0.005,\"failure_fraction\":0.05,\"response_headers\":[\"Via\"]}",
"x-powered-by": "Express",
"access-control-allow-origin": "*",
"etag": "W/\"2-vyGp6PvFo4RvsFtPoIWeCReyIC8\"",
"via": "1.1 vegur",
"cache-control": "max-age=14400",
"cf-cache-status": "EXPIRED",
"vary": "Accept-Encoding",
"server": "cloudflare",
"cf-ray": "8ef52eac9d99be0c-DUB",
"server-timing": "cfL4;desc=\"?proto=TCP&rtt=1656&min_rtt=1516&rtt_var=668&sent=3&recv=5&lost=0&retrans=0&sent_bytes=2819&recv_bytes=622&delivery_rate=1883905&cwnd=251&unsent_bytes=0&cid=60b413e67942d5e6&ts=33&x=0\""
},
"status": 404
},
"files": []
}

GET (file download)

Step Configuration
name: Step rest-new
description: ""
config:
endpoint:
url: https://cataas.com/cat
method: GET
restRequest: JSON
expectedResponseLocation: file
targetPath: result
headers: {}
oAuthConfig: {}
mtlsConfig: {}
json: {}
disableHeadersInKey: false
stepType: rest-new
condition: ""
Flow Result with downloaded file reference in document
{
"doc": {
"result": {
"id": "d20d36d7-ee74-44e4-850d-182b8ebea062",
"fileName": "ace-download.jpeg",
"extension": "jpeg",
"contentType": "image/jpeg",
"detectedExtension": "jpg",
"detectedMimeType": "image/jpeg"
}
},
"errors": [],
"performance": {
"steps": [
{
"step": "Step rest-new",
"executionTime": 273
}
],
"executionTimeOfFlow": 273,
"timeMetric": "ms"
},
"headers": {
"request": {
"content-type": "application/json"
},
"response": {
"server": "nginx",
"date": "Mon, 09 Dec 2024 13:04:27 GMT",
"content-type": "image/jpeg",
"content-length": "28304",
"connection": "close",
"set-cookie": [
"session=7ce715c1-21fa-49f5-8e2c-8412eb4bc8a8; Path=/; SameSite=Strict; Secure; HttpOnly"
],
"access-control-allow-origin": "*",
"access-control-allow-headers": "X-Requested-With, Content-Type, Accept, Origin, Authorization",
"access-control-allow-methods": "GET, POST, PUT, DELETE, OPTIONS"
},
"status": 200
},
"response": {
"req": {
"method": "GET",
"url": "https://cataas.com/cat",
"data": {},
"headers": {
"content-type": "application/json"
}
},
"header": {
"server": "nginx",
"date": "Mon, 09 Dec 2024 13:04:27 GMT",
"content-type": "image/jpeg",
"content-length": "28304",
"connection": "close",
"set-cookie": [
"session=7ce715c1-21fa-49f5-8e2c-8412eb4bc8a8; Path=/; SameSite=Strict; Secure; HttpOnly"
],
"access-control-allow-origin": "*",
"access-control-allow-headers": "X-Requested-With, Content-Type, Accept, Origin, Authorization",
"access-control-allow-methods": "GET, POST, PUT, DELETE, OPTIONS"
},
"status": 200
},
"files": [
{
"targetProperty": "result",
"files": [
{
"fileBase64": "/9j/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAJYAcIDASIAAhEBAxEB/8QAHAAAAQUBAQEAAAAAAAAAAAAAAgABAwQFBgcI/8QAQhAAAQMDAgQEBAMGBQQCAgMBAQACAwQRIQUxEkFRYQYTInEygZGhFEKxByNSwdHwJDNicuEVQ4LxU5IWsiU0RKL/xAAZAQEBAQEBAQAAAAAAAAAAAAAAAQIDBAX/xAAtEQEBAAICAgICAgAEBwEAAAAAAQIRAyESMQRBEyIyUQUUYYEjM3GRobHR4f/opvMtukkkg/9k=",
"fileName": "ace-download.jpeg",
"id": "d20d36d7-ee74-44e4-850d-182b8ebea062",
"mimeType": "image/jpeg"
}
]
}
]
}

POST

Flow Input
{
"name": "Jane Doe"
}
Step Configuration
name: rest-new
description: ""
config:
endpoint:
url: https://60927f7f85ff510017212f24.mockapi.io/users
method: POST
restRequest: JSON
expectedResponseLocation: body
targetPath: result
headers: {}
oAuthConfig: {}
json:
name: "{{name}}"
disableHeadersInKey: false
stepType: rest-new
condition: ""
Flow Result
{
"doc": {
"name": "Jane Doe",
"result": {
"createdAt": "2024-12-09T09:50:40.629Z",
"name": "Jane Doe",
"avatar": "https://cloudflare-ipfs.com/ipfs/Qmd3W5DuhgHirLHGVixi6V76LhCkZUz6pnFt5AJBiyvHye/avatar/828.jpg",
"id": "35"
}
},
"errors": [],
"performance": {
"steps": [
{
"step": "rest-new",
"executionTime": 310
}
],
"executionTimeOfFlow": 310,
"timeMetric": "ms"
},
"files": [
{
"targetProperty": "result",
"files": []
}
]
}
Example Flow
tags:
- example
steps:
- stepType: rest-new
config:
endpoint:
url: https://60927f7f85ff510017212f24.mockapi.io/users
method: POST
queryParams: {}
headers: {}
restRequest: JSON
expectedResponseLocation: body
oAuthConfig: {}
json:
name: "{{name}}"
targetPath: result
disableHeadersInKey: false
name: REST Http
description: ""
condition: ""
sampleData:
name: Jane Doe

PUT

Flow Input
{
"id": 4
}
Step Configuration
name: rest-new
description: ""
config:
endpoint:
url: https://60927f7f85ff510017212f24.mockapi.io/users/{{id}}
method: PUT
restRequest: JSON
expectedResponseLocation: body
targetPath: result
headers: {}
oAuthConfig: {}
json:
name: John Doe
disableHeadersInKey: false
stepType: rest-new
condition: ""
Flow Result
{
"doc": {
"id": 4,
"result": {
"createdAt": "2021-10-10T12:58:02.333Z",
"name": "John Doe",
"avatar": "https://cdn.fakercloud.com/avatars/konus_128.jpg",
"id": "4"
}
},
"errors": [],
"performance": {
"steps": [
{
"step": "rest-new",
"executionTime": 448
}
],
"executionTimeOfFlow": 448,
"timeMetric": "ms"
},
"files": [
{
"targetProperty": "result",
"files": []
}
]
}
Example Flow
tags:
- example
steps:
- stepType: rest-new
config:
endpoint:
url: https://60927f7f85ff510017212f24.mockapi.io/users/{{id}}
method: PUT
queryParams: {}
headers: {}
restRequest: JSON
expectedResponseLocation: body
oAuthConfig: {}
json:
name: John Doe
targetPath: result
disableHeadersInKey: false
name: REST Http
description: ""
condition: ""
sampleData:
id: 4

PATCH

Flow Input
{
"id": 4
}
Step Configuration
name: rest-new
description: ""
config:
endpoint:
url: https://60927f7f85ff510017212f24.mockapi.io/users/{{id}}
method: PATCH
restRequest: JSON
expectedResponseLocation: body
targetPath: result
headers: {}
oAuthConfig: {}
json:
name: John Doe
disableHeadersInKey: false
stepType: rest-new
condition: ""
Flow Result
{
"doc": {
"id": 4,
"result": {
"createdAt": "2021-10-10T12:58:02.333Z",
"name": "John Doe",
"avatar": "https://cdn.fakercloud.com/avatars/konus_128.jpg",
"id": "4"
}
},
"errors": [],
"performance": {
"steps": [
{
"step": "rest-new",
"executionTime": 340
}
],
"executionTimeOfFlow": 341,
"timeMetric": "ms"
},
"files": [
{
"targetProperty": "result",
"files": []
}
]
}
Example Flow
tags:
- example
steps:
- stepType: rest-new
config:
endpoint:
url: https://60927f7f85ff510017212f24.mockapi.io/users/{{id}}
method: PATCH
queryParams: {}
headers: {}
restRequest: JSON
expectedResponseLocation: body
oAuthConfig: {}
json:
name: John Doe
targetPath: result
disableHeadersInKey: false
name: REST Http
description: ""
condition: ""
sampleData:
id: 4

DELETE

Flow Input
{
"id": 5
}
Step Configuration
name: rest-new
description: ""
config:
endpoint:
url: https://60927f7f85ff510017212f24.mockapi.io/users/{{id}}
method: DELETE
restRequest: JSON
expectedResponseLocation: body
targetPath: result
headers: {}
oAuthConfig: {}
json: {}
disableHeadersInKey: false
stepType: rest-new
condition: ""
Flow Result
{
"doc": {
"id": 5,
"result": {
"createdAt": "2021-10-10T02:26:35.477Z",
"name": "Bert Windler",
"avatar": "https://cdn.fakercloud.com/avatars/jedbridges_128.jpg",
"id": "5"
}
},
"errors": [],
"performance": {
"steps": [
{
"step": "rest-new",
"executionTime": 622
}
],
"executionTimeOfFlow": 623,
"timeMetric": "ms"
},
"files": [
{
"targetProperty": "result",
"files": []
}
]
}
Flow Example
tags:
- example
steps:
- stepType: rest-new
config:
endpoint:
url: https://60927f7f85ff510017212f24.mockapi.io/users/{{id}}
method: DELETE
queryParams: {}
headers: {}
restRequest: JSON
expectedResponseLocation: body
oAuthConfig: {}
json: {}
targetPath: result
disableHeadersInKey: false
name: REST Http
description: ""
condition: ""
sampleData:
id: 5