request

Send a GET, POST, PUT, or DELETE request to a remote URL.

Properties

objectRequired

An object containing the following properties.

request.url

stringRequired

URL to send the HTTPS request to. Authentication can also be set in the url in the format of username:password@url.

request.method

stringRequired

Request type. GET|POST|PUT|DELETE. A SWML variable reference is also accepted; it must resolve to one of these methods.

request.headers

object

Object mapping HTTP header names to string values. Valid header names are Accept, Authorization, Content-Type, and Range (case-insensitive), and custom headers that start with X- (or x-) followed by one or more ASCII letters, digits, hyphens, or underscores.

Header values support variable substitution. After substitution, a value must be non-empty and contain only printable ASCII characters (spaces included) other than the backslash; tabs, line breaks, and non-ASCII characters aren’t allowed. Entries with an invalid name, a non-string value, or an invalid value are skipped with a warning, and the request is still sent.

request.body

string | object

Request body. Content-Type header should be explicitly set, but if not set, the most likely type will be set based on the first non-whitespace character.

request.connect_timeout

numberDefaults to 5

Maximum time in seconds to wait for a connection, applied in whole seconds. A value of 0 uses the default, and values above 30 are capped at 30 seconds.

request.timeout

numberDefaults to 5

Maximum time in seconds to wait for a response, applied in whole seconds. A value of 0 uses the default, and values above 30 are capped at 30 seconds.

request.save_variables

booleanDefaults to false

Store parsed JSON response as variables

Variables

Set by the method:

request_url: (out) URL the request was sent to.
request_result: (out) success when the HTTP response code is from 200 to 299, otherwise failed, including when no response code is received. This result is based only on the response code, not on whether the body parses as JSON. A failed result doesn’t by itself stop the document; execution continues with the next method.
request_response_code: (out) HTTP response code from the request.
request_response_headers.<header name lowercase>: (out) HTTP response headers. Header names are converted to lowercase, and header values are trimmed of surrounding whitespace. Ex: ${request_response_headers.content-type}.
request_response_body: (out) Raw HTTP response body. This is limited to 64KB.
request_response.<object_field>: (out) Variables saved from the response if save_variables is true and parsed as JSON. The parsed response can nest objects and arrays at most 62 levels deep, counting the outermost object or array. A parsed response nested deeper than that isn’t saved, and a relay_script_nested_too_deep warning is reported. A response that isn’t valid JSON isn’t saved either, and no warning is reported. The same applies to a response nested so deeply that it can’t be read as JSON at all.

For example, if the server responds with the following JSON:

  { "status": "created", "time": "2 seconds ago", "number": { "home": "n/a" } }

The variables request_response.status, request_response.time, and request_response.number.home are set.

Examples

Making a GET Request

version: 1.0.0
sections:
  main:
    - answer: {}
    - request:
        url: 'https://jsonplaceholder.typicode.com/todos/1'
        method: GET
        save_variables: true
        timeout: 10
    - play:
        url: 'say: the title is: ${request_response.title}'