Skip to main content
Version: ACE 4

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 location of the response in the response object. 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 checkbox, and when checked, the step first performs authentication against some authentication server, and then adds the generated token to the request.

In order to perform such authentication, along with checking the OAuth 2.0 checkbox, 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.

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")

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.

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 and data is not cached, 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 or Form data - Data to be sent with the request.

If content-type header is not set in headers then selecting JSON, XML, TEXT or Form data will set content-type in headers as application/json, application/xml, text/plain or multipart/form-data 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
{
  "stepType": "rest-new",
  "color": "rgb(247,225,211)",
  "displayName": "REST Http",
  "isSelected": true,
  "config": {
    "endpoint": {
      "url": "https://60927f7f85ff510017212f24.mockapi.io/users"
    },
    "queryParams": {},
    "headers": {},
    "restRequest": "JSON",
    "expectedResponseLocation": "body",
    "oAuthConfig": {},
    "json": {},
    "targetPath": "result",
    "headerPath": "headers"
  }
}
Flow Result
{
  "doc": {
    "headers": {
      "request": {
        "Content-Type": "application/json"
      },
      "response": {
        "server": "Cowboy",
        "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": "674",
        "etag": "\"-959759345\"",
        "vary": "Accept-Encoding",
        "date": "Sun, 10 Oct 2021 15:51:58 GMT",
        "via": "1.1 vegur"
      }
    },
    "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": "Diane Heaney",
        "avatar": "https://cdn.fakercloud.com/avatars/konus_128.jpg",
        "id": "4"
      },
      {
        "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": 334
      }
    ],
    "executionTimeOfFlow": 335,
    "timeMetric": "ms"
  }
}

GET (with errors)​

Step Configuration
{
  "stepType": "rest-new",
  "color": "rgb(247,225,211)",
  "displayName": "REST Http",
  "isSelected": true,
  "config": {
    "endpoint": {
      "url": "https://dev.ace-mockbin.sapienspaas.com/status/404/error"
    },
    "restRequest": "JSON",
    "expectedResponseLocation": "body",
    "oAuthConfig": {},
    "json": {},
    "queryParams": {},
    "headers": {},
    "targetPath": "result"
  }
}
Flow Result
{
  "doc": {},
  "errors": [
    {
      "error": "Error in flow 'FlowName' : Rest API step: {\n  'code': '404',\n  'message': 'error'\n} ResponseCode: 404",
      "body": {
        "request": {},
        "response": {
          "code": "404",
          "message": "error"
        }
      },
      "headers": {
        "request": {
          "Content-Type": "application/json"
        },
        "response": {}
      },
      "statusCode": 404
    }
  ],
  "performance": {
    "steps": [
      {
        "step": "rest-new",
        "executionTime": 239
      }
    ],
    "executionTimeOfFlow": 241,
    "timeMetric": "ms"
  }
}

GET (file download)​

Step Configuration
{
  "stepType": "rest-new",
  "color": "rgb(247,225,211)",
  "displayName": "REST HTTP",
  "isSelected": true,
  "config": {
    "endpoint": {
      "url": "https://cataas.com/cat",
      "method": "GET"
    },
    "restRequest": "JSON",
    "expectedResponseLocation": "file",
    "oAuthConfig": {},
    "mtlsConfig": {},
    "json": {},
    "targetPath": "result",
    "disableHeadersInKey": false
  }
}
Flow Result with downloaded file reference in document
{
  "doc": {
    "result": {
      "id": "c3f457c8-bd11-4cab-91f4-9380cd432e92",
      "fileName": "ace-download.png",
      "extension": "png",
      "contentType": "image/png",
      "detectedExtension": "png",
      "detectedMimeType": "image/png"
    }
  },
  "headers": {
    "request": {
      "content-type": "application/json"
    },
    "response": {
      "server": "nginx",
      "date": "Thu, 18 Jan 2024 07:42:23 GMT",
      "content-type": "image/png",
      "content-length": "32117",
      "connection": "close",
      "set-cookie": [
        "session=a130e0eb-2204-4148-a0cc-3e1f0ac8cb3e; 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"
    }
  },
  "response": {
    "req": {
      "method": "GET",
      "url": "https://cataas.com/cat",
      "data": {},
      "headers": {
        "content-type": "application/json"
      }
    },
    "header": {
      "server": "nginx",
      "date": "Thu, 18 Jan 2024 07:42:23 GMT",
      "content-type": "image/png",
      "content-length": "32117",
      "connection": "close",
      "set-cookie": [
        "session=a130e0eb-2204-4148-a0cc-3e1f0ac8cb3e; 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
  },
  "errors": [],
  "performance": {
    "steps": [
      {
        "step": "rest-new",
        "executionTime": 205
      }
    ],
    "executionTimeOfFlow": 206,
    "timeMetric": "ms"
  }
}

POST​

Flow Input
{
  "name": "Jane Doe"
}
Step Configuration
{
  "stepType": "rest-new",
  "color": "rgb(247,225,211)",
  "displayName": "REST Http",
  "isSelected": true,
  "config": {
    "endpoint": {
      "url": "https://60927f7f85ff510017212f24.mockapi.io/users",
      "method": "POST"
    },
    "queryParams": {},
    "headers": {},
    "restRequest": "JSON",
    "expectedResponseLocation": "body",
    "oAuthConfig": {},
    "json": {
      "name": "{{name}}"
    },
    "targetPath": "result"
  }
}
Flow Result
{
  "doc": {
    "name": "Jane Doe",
    "result": {
      "createdAt": "2021-10-10T00:08:16.288Z",
      "name": "Jane Doe",
      "avatar": "https://cdn.fakercloud.com/avatars/enda_128.jpg",
      "id": "5"
    }
  },
  "errors": [],
  "performance": {
    "steps": [
      {
        "step": "rest-new",
        "executionTime": 359
      }
    ],
    "executionTimeOfFlow": 360,
    "timeMetric": "ms"
  }
}
Example Flow
{
  "id": "18489e5b-5d61-4efe-babe-37ed6d16f179",
  "name": "exampleRest",
  "flow": {
    "name": "exampleRest",
    "description": "",
    "steps": [
      {
        "stepType": "rest-new",
        "color": "rgb(247,225,211)",
        "displayName": "REST Http",
        "isSelected": true,
        "config": {
          "endpoint": {
            "url": "https://60927f7f85ff510017212f24.mockapi.io/users",
            "method": "POST"
          },
          "queryParams": {},
          "headers": {},
          "restRequest": "JSON",
          "expectedResponseLocation": "body",
          "oAuthConfig": {},
          "json": {
            "name": "{{name}}"
          },
          "targetPath": "result"
        }
      }
    ]
  },
  "inputSchema": {
    "name": "Jane Doe"
  },
  "createDate": "2021-10-10T15:47:59.256Z",
  "tags": ["example"],
  "inputSchemaLabel": "",
  "version": 1
}

PUT​

Flow Input
{
  "id": 4
}
Step Configuration
{
  "stepType": "rest-new",
  "color": "rgb(247,225,211)",
  "displayName": "REST Http",
  "isSelected": true,
  "config": {
    "endpoint": {
      "url": "https://60927f7f85ff510017212f24.mockapi.io/users/{{id}}",
      "method": "PUT"
    },
    "queryParams": {},
    "headers": {},
    "restRequest": "JSON",
    "expectedResponseLocation": "body",
    "oAuthConfig": {},
    "json": {
      "name": "John Doe"
    },
    "targetPath": "result"
  }
}
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": 381
      }
    ],
    "executionTimeOfFlow": 381,
    "timeMetric": "ms"
  }
}
Example Flow
{
  "id": "18489e5b-5d61-4efe-babe-37ed6d16f179",
  "name": "exampleRest",
  "flow": {
    "name": "exampleRest",
    "description": "",
    "steps": [
      {
        "stepType": "rest-new",
        "color": "rgb(247,225,211)",
        "displayName": "REST Http",
        "isSelected": true,
        "config": {
          "endpoint": {
            "url": "https://60927f7f85ff510017212f24.mockapi.io/users/{{id}}",
            "method": "PUT"
          },
          "queryParams": {},
          "headers": {},
          "restRequest": "JSON",
          "expectedResponseLocation": "body",
          "oAuthConfig": {},
          "json": {
            "name": "John Doe"
          },
          "targetPath": "result"
        }
      }
    ]
  },
  "inputSchema": {
    "id": 4
  },
  "createDate": "2021-10-10T15:47:59.256Z",
  "tags": ["example"],
  "inputSchemaLabel": "",
  "version": 1
}

PATCH​

Flow Input
{
  "id": 4
}
Step Configuration
{
  "stepType": "rest-new",
  "color": "rgb(247,225,211)",
  "displayName": "REST Http",
  "isSelected": true,
  "config": {
    "endpoint": {
      "url": "https://60927f7f85ff510017212f24.mockapi.io/users/{{id}}",
      "method": "PATCH"
    },
    "queryParams": {},
    "headers": {},
    "restRequest": "JSON",
    "expectedResponseLocation": "body",
    "oAuthConfig": {},
    "json": {
      "name": "John Doe"
    },
    "targetPath": "result"
  }
}
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": 329
      }
    ],
    "executionTimeOfFlow": 329,
    "timeMetric": "ms"
  }
}
Example Flow
{
  "id": "18489e5b-5d61-4efe-babe-37ed6d16f179",
  "name": "exampleRest",
  "flow": {
    "name": "exampleRest",
    "description": "",
    "steps": [
      {
        "stepType": "rest-new",
        "color": "rgb(247,225,211)",
        "displayName": "REST Http",
        "isSelected": true,
        "config": {
          "endpoint": {
            "url": "https://60927f7f85ff510017212f24.mockapi.io/users/{{id}}",
            "method": "PATCH"
          },
          "queryParams": {},
          "headers": {},
          "restRequest": "JSON",
          "expectedResponseLocation": "body",
          "oAuthConfig": {},
          "json": {
            "name": "John Doe"
          },
          "targetPath": "result"
        }
      }
    ]
  },
  "inputSchema": {
    "id": 4
  },
  "createDate": "2021-10-10T15:47:59.256Z",
  "tags": ["example"],
  "inputSchemaLabel": "",
  "version": 1
}

DELETE​

Flow Input
{
  "id": 5
}
Step Configuration
{
  "stepType": "rest-new",
  "color": "rgb(247,225,211)",
  "displayName": "REST Http",
  "isSelected": true,
  "config": {
    "endpoint": {
      "url": "https://60927f7f85ff510017212f24.mockapi.io/users/{{id}}",
      "method": "DELETE"
    },
    "queryParams": {},
    "headers": {},
    "restRequest": "JSON",
    "expectedResponseLocation": "body",
    "oAuthConfig": {},
    "json": {},
    "targetPath": "result"
  }
}
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": 362
      }
    ],
    "executionTimeOfFlow": 362,
    "timeMetric": "ms"
  }
}
Flow Example
{
  "id": "18489e5b-5d61-4efe-babe-37ed6d16f179",
  "name": "exampleRest",
  "flow": {
    "name": "exampleRest",
    "description": "",
    "steps": [
      {
        "stepType": "rest-new",
        "color": "rgb(247,225,211)",
        "displayName": "REST Http",
        "isSelected": true,
        "config": {
          "endpoint": {
            "url": "https://60927f7f85ff510017212f24.mockapi.io/users/{{id}}",
            "method": "DELETE"
          },
          "queryParams": {},
          "headers": {},
          "restRequest": "JSON",
          "expectedResponseLocation": "body",
          "oAuthConfig": {},
          "json": {},
          "targetPath": "result"
        }
      }
    ]
  },
  "inputSchema": {
    "id": 5
  },
  "createDate": "2021-10-10T15:47:59.256Z",
  "tags": ["example"],
  "inputSchemaLabel": "",
  "version": 1
}