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"
    }
  ]
}
info

Read about file references.

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 (endpoint.url)​

Request url for the REST service.

Method (endpoint.method)​

The REST method type (Default is GET).

Target path (targetPath)​

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

Header path (headerPath)​

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

Cache result (cacheble)​

If checked will enable caching response values.

Ignore headers in cache key (disableHeadersInKey)​

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

Cache Key (cacheKey)​

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

Cache clean-up condition (cacheCleanupCondition)​

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

TTL cache (minutes) (ttl)​

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

Response Timeout (responseTimeout)​

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

Deadline Timeout (deadlineTimeout)​

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

Query Params (queryParams)​

The query params to send in the REST request.

HTTP Headers (headers)​

HTTP headers to send in the REST request.

Request Body Type (restRequest)​

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 in the form (fieldName)​

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

Base64 string (base64string)​

Base64-encoded file content to send

Custom file name (fileName)​

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

Response format (expectedResponseLocation)​

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 (appendErrors)​

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

Ignore redirects (ignoreRedirects)​

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