request Action #

The request action carries out a single HTTP or HTTPS request to load content from remote upstream servers. If you want to do multiple requests in parallel, use the requests action instead. To pass an incoming request almost unmodified to an upstream system, use the proxy-request action.

Syntax #

Usage #

You can use a JSON template with the features defined below.

Example: GET request

<request content="my_request">
{
  "url": "http://www.example.com/foo",
  "method": "GET",
  "headers": {
    "User-Agent": "foo",
    "X-Foo": "value 1, value 2"
  },
  "query": {
    "a": 37,
    "b": "c"
  }
}
</request>

Example: POST request

<request content="my_request">
{
  "url": "http://www.example.com/foo",
  "method": "POST",
  "headers": {
    "User-Agent": "foo",
    "X-Foo": "value 1, value 2"
  },
  "post": [
    { "name": "a", "value": "b" },
    { "name": "a", "value": "foo" }
  ]
}
</request>

The response body will be written into fit://request/content/<ID> and can be accessed with the body function or the content function. Additional information about the response, such as headers and status code can be found in the $upstream variable.

id #

The id property sets the request ID. If id is set in the JSON object, is not null and not "", it will be used and a content attribute on the request element will be ignored.

encoding #

The encoding property sets the character encoding used for the URI including the query string and POST form data. Its value must be a string. The default value is UTF-8.

url #

The url property sets the request URL. If url is set in the JSON object, is not null and not "", it will be used and a url attribute on the request element will be ignored.

Example:

"url": "http://www.example.com/api/v1/endpoint"

method #

The method property sets the request method. Its value must be a string. If method is set in the JSON object, is not null and not "", it will be used and a method attribute on the request element will be ignored.

The default value is GET. However, if post, upload or body are set in the JSON object, the default value will be POST.

Example:

"method": "POST"

headers #

The headers property sets the request headers. Its value must be a JSON object, with each header field name and value set as properties with values of the JSON objects. If multiple header fields with the same name should be set, the values must be concatenated in advance.

Example:

"headers": {
  "User-Agent": "foo",
  "content-type": "application/octet-stream",
  "X-Foo": {{ concat("value1", ",", "value2") }}
}

cookies #

The cookies property sets the cookies, i.e. it sets a Cookie request header. Its value must be one of the following:

If the value is either a non-empty JSON object or a non-empty array, any Cookie header set via headers will be ignored.

Example: cookies as a JSON object

"cookies": {
  "a": "b",
  "c": "foo"
}

Example: cookies as an array

"cookies": [
  { "name": "a", "value": "b" },
  { "name": "c", "value": "foo" }
]

query #

The query string of the request URL can be set as part of url. The query property sets the query string explicitly. Its value must be one of the following:

Example: query as a string

"query": "a=12&b=foo&a=13"

Example: query as a JSON object

"query": {
  "a": 37,
  "b": "c"
}

Example: query as an array

"query": [
  { "name": "a", "value": 12 },
  { "name": "a", "value": "foo" }
]

post #

The post property sets the post parameters (an x-www-form-urlencoded request body). Its value must be one of the following:

Example: post as a JSON object

"post": {
  "a": "b",
  "c": "foo"
}

Example: post as an array

"post": [
  { "name": "a", "value": "b" },
  { "name": "a", "value": "foo" }
]

📎 If both post and body are set, post wins.

body #

The body property sets the request body, in case the body is not x-www-form-urlencoded. Its value must be a JSON object with either

The optional mime property sets the Content-Type request header. If no mime property is set, the content type is determined automatically.

Example: body with src using the predefined $body variable to pass the incoming request body

"body": {
  "src": "$body"
}

Example: body with src using a URL

"body": {
  "src": "fit://site/conf/body.xml",
  "mime": "application/xml+foo"
}

Example: body with string value

"body": {
  "value": "boohooo",
  "mime": "text/plain"
}

Example: body with JSON value

"body": {
  "value": {
    "user": "fred",
    "pass": "wilma"
  },
  "mime": "application/json"
}

Example: body with template placeholder

"body": {
  "value": {{ $body }},
  "mime": "text/plain"
}

📎 If both body and post are set, post wins.

uploads #

The uploads property sets the content to be uploaded. Its value must be an array of JSON objects with at least

and

The optional filename property sets the filename. The optional mime property set the MIME type of the uploaded content.

Example: uploads with src or value

"uploads": [
  {
    "name": "foo_html",
    "src": "fit://site/conf/foo.html",
    "filename": "foo.html",
    "mime": "text/html"
  },
  {
    "name": "foo_json",
    "src": "$json",
    "filename": "foo.json"
  },
  {
    "name": "foo_text",
    "value": "some random text",
    "filename": "foo.txt"
  }
]

options #

The options property sets the request options. Its value must be a JSON object. The following options are valid:

Example:

"options": {
  "timeout": 5,
  "follow-redirects": true,
  "max-redirects": 10,
  "basic-auth-credentials": "user:s3CreT",
  "validate-response": true,
  "set-response-headers": {
    "Cache-Control": "s-maxage=3600",
    "Set-Cookie": [ "a=1", "b=2" ]
  }
}

See also #