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 theContent-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 idfileName
- file name (locked asace-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.
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.
{
"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.
{
"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
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: ""
{
"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)
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: ""
{
"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)
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: ""
{
"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
{
"name": "Jane Doe"
}
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: ""
{
"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": []
}
]
}
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
{
"id": 4
}
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: ""
{
"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": []
}
]
}
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
{
"id": 4
}
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: ""
{
"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": []
}
]
}
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
{
"id": 5
}
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: ""
{
"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": []
}
]
}
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