Request Object

The request object allows you to submit a POST or GET request to an URL. Essentially it provides a way to make REST API requests to another URL.

An example scenario is if you need to submit form information to a 3rd party as well as save it within the CMS. In that case, you can set up a Post Process Script for the form to build the data to send and submit it to an URL as a POST submission.

You can also send HEAD, PUT, DELETE, OPTIONS and PATCH requests.

The current URL is automatically set as the "Referer" header value.

Example

Below is an example POST request. It's using the fantastic httpbin.org service to simulate requests and responses.

{% set request = _core.request.getObject('http://httpbin.org/post') %}
{% do request.addParam('test', 'test value') %}
{% do request.addParam('anotherParam', 'test post value') %}
{% do request.setAuthentication('testusername', 'testpassword') %}
{% do request.post() %}

The first thing that you do is get the request object by calling _core.request.getObject() and saving that to a variable. We use "request" as the variable name, but you could use any name that you want.

Passing the URL to _core.request.getObject() is optional, but it saves a step. If you didn't pass the URL then you would need to call

{% do request.setUrl('http://httpbin.org/post') %}

You can create multiple request objects by calling _core.request.getObject() again and assigning it to another variable.

{% do anotherRequest = _core.request.getObject('http://www.anothersite.com/api') %}
{% do anotherRequest.addParam('color', 'blue') %}
{% do anotherRequest.post() %}

Back to the example, the next thing we do is pass a couple of parameters.

{% do request.addParam('test', 'test value') %}
{% do request.addParam('anotherParam', 'test post value') %}

The first parameter's name is "test" and its value is "test value". The second parameter's name is "anotherParam" and its value is "test post value". Since this is going to be a POST request the parameters will be sent as form parameters. If this was a GET request then they would be sent as URL parameters.

Alternately, you could set the entire body of the request like this:

{% do request.setBody('body value') %}

This would be useful if you had to submit XML in your request.

If you're setting JSON you can use the setJsonBody method.

{% do request.setJsonBody(myJson) %}

Next, in our example, we set the authentication to send with the request.

{% do request.setAuthentication('testusername', 'testpassword') %}

Not all requests need authentication. That will depend on the service you are submitting to. 

Finally, we submit our request.

{% do request.post() %}

Sending files

You can send files with the POST or PATCH request. The request object will retrieve the contents of the file and include those with the submission.

There are two ways to add files to the request. The first is to pass the file contents.

{% do request.addFile('file contents', 'file.txt', 'myfile') %}

The second is to pass the URL to the file.

{% do request.addFileByUrl('http://www.site.com/path/to/file.pdf', 'myfile') %}

Submitting requests

There are a few ways to submit the request. You could use the send() method or one of the request type methods like post().

If you send the request using send() , you need to pass the type of request ('delete', 'get', 'head','options', 'patch', 'post', or 'put')

{% do request.send('post') %}

Submit using one of the request type methods.

{% do request.delete() %}
{% do request.head() %}
{% do request.get() %}
{% do request.options() %}
{% do request.patch() %}
{% do request.post() %}
{% do request.put() %}

Getting response data

After you submit your request you can retrieve some information about the response.

Errors

Test to see if there were any errors in the request and if so get the error.

{% if request.hasError() %}
    {% set error = request.getError() %}
{% endif %}

Response body

If there were no errors then the entire response body can be retrieved. Internally the system checks first to make sure that there were no errors and that the response is valid. If so it will be returned as a string.

{% set response = request.getResponseBody() %}

XML response

If the request's response is XML then you can get the response returned as an array instead of a XML string to make it easier to process the data.

{% set response = request.getResponseXml() %}

JSON response

If the request's response is JSON then you can get the response returned as an array instead of a JSON string to make it easier to process the data.

{% set response = request.getResponseJson() %}

Response headers

If there were no errors then the response headers can be retrieved. Internally the system checks first to make sure that there were no errors and that the response is valid. If so it will be returned as an array.

{% set headers = request.getResponseHeaders() %}

The headers are returned as an array. Below is an example.

Array
(
    [Connection] => Array
    (
        [0] => keep-alive
    )
    [Server] => Array
    (
        [0] => gunicorn/19.7.1
    )
    [Content-Type] => Array
    (
        [0] => application/json
    )
    [Content-Length] => Array
    (
        [0] => 449
    )
)

Troubleshooting

If you are having trouble with the request you can get some information about the request to ensure that what you are sending is correct.

You must first submit the request in order to get the correct request information.

{% set request = _core.request.getObject('http://httpbin.org/post') %}
{% do request.addParam('test', 'test value') %}
{% do request.post() %}
{% set requestBody = request.getRequestBody() %}
{% set requestHeaders = request.getRequestHeaders() %}
{{ requestBody|debug('Request body') }}
{{ requestHeaders|debug('Request headers') }}

That will allow you to see the headers and the request body that is being submitted.

List of request methods

Below is a list of all methods for the request object. In all of the code samples the request object has been saved to a variable called "request".

Method Description
_core.request.getObject()

Gets the request object. You would always be saving this to a variable and then using that variable to continue working with the request object.

Parameters

  • url: (string) (optional) The URL that the request is for.

Examples

{% set request = _core.request.getObject() %}

Optionally you can pass the URL that the request is for.

{% set request = _core.request.getObject('http://www.apisite.com/api') %}
addFile

Adds a file to include in the submission by passing the file contents. The "Content-Type" header will be set to "multipart/form-data" for the request.

Parameters

  • file: (string) The contents of the file.
  • fileName: (string) The name of the file including the file extension.
  • fieldName: (string) The field parameter name for the file. If the file is part of a form upload then use the form field name. Otherwise, pass a unique name. This is different from the file name.

Example

{% do request.addFile('file contents', 'file.txt', 'myfile') %}

A typical scenario where this may be used is within a Post Process Script for forms. Your form may have one or more upload fields and you need to send the files as part of the request. Below is an example of how that could be done.

{% do request.addFile(form.fields.myFileField.fileContents, form.fields.myFileField.filename, form.fields.myFileField.name) %}

Or if looping through the fields:

{% for field in form.fields %}
    {% if field.type == 'file' %}
        {% do request.addFile(field.fileContents, field.filename, field.name) %}
    {% endif %}
{% endfor %}
addFileByUrl

Adds a file to include in the submission by specifying the full URL to retrieve the file from. The "Content-Type" header will be set to "multipart/form-data" for the request.

Parameters

  • file: (string) The full URL to the file.
  • fieldName: (string) The field parameter name for the file. If the file is part of a form upload then use the form field name. Otherwise, pass a unique name. This is different from the file name.

Example

{% do request.addFileByUrl('http://www.site.com/path/to/file.pdf', 'myfile') %}
addHeader

Adds a header for the request.

Parameters

  • name: (string) (required) The name of the header.
  • value: (string) (required) The header value

Example

{% do request.addHeader('Content-Type', 'application/json') %}
addParam

Adds a parameter for either a GET or POST request.

If the request type is 'get' then the parameters will be added to the request URL as URL parameters replacing any existing URL parameters.

If the request type is 'post' then the parameters will be submitted as form parameters.

You would call this method for each parameter that you need to add to the request.

Parameters

  • name: (string) (required) The parameter name
  • value: (string) (required) The parameter value

Example

{% do request.addParam('paramName', 'value') %}
delete

Sends the request as a DELETE request.

Example

{% set request = _core.request.getObject('http://httpbin.org/delete') %}
{% do request.delete() %}
get

Sends the request as a GET request.

Example

{% set request = _core.request.getObject('http://httpbin.org/get') %}
{% do request.get() %}
getError

Returns the error from sending the request if there was one.

Example

{% set request = _core.request.getObject('http://httpbin.org/post') %}
{% do request.addParam('name', 'Bob') %}
{% do request.post() %}
{% if request.hasError() %}
    {{ request.getError()|debug('Error') }}
{% endif %}
getErrorCode

Returns the HTTP response code if the request resulted in an error. This could be a 4xx or 5xx error.

Example

{% set request = _core.request.getObject('http://httpbin.org/post') %}
{% do request.addParam('name', 'Bob') %}
{% do request.post() %}
{% if request.hasError() %}
{% do http_response_code(request.getErrorCode()) %}
  {"error": "{{ request.getError() }}"}
{% else %}
  {{ request.getResponseBody() }}
{% endif %}
getRequestBody

Gets the body that was sent in the request. A string is returned.

The request must be sent first otherwise an error will be returned.

Example

{% set request = _core.request.getObject('http://httpbin.org/post') %}
{% do request.setBody('request body') %}
{% do request.post() %}
{{ request.getRequestBody()|debug('Request Body') %}
getRequestHeaders

Gets the headers that were sent on the request.

The request must be sent first otherwise an error will be returned.

Example

{% set request = _core.request.getObject('http://httpbin.org/post') %}
{% do request.addParam('name', 'Bob') %}
{% do request.post() %}
{% set headers = request.getRequestHeaders() %}
{{ headers|debug('Request headers') %}

Returned data

An array is returned. Below is an example response.

Array
(
    [Connection] => Array
    (
        [0] => keep-alive
    )
    [Server] => Array
    (
        [0] => gunicorn/19.7.1
    )
    [Content-Type] => Array
    (
        [0] => application/json
    )
    [Content-Length] => Array
    (
        [0] => 449
    )
)
getResponseBody

Gets the body from the response. A string is returned.

Example

{% set request = _core.request.getObject('http://httpbin.org/get') %}
{% do request.get() %}
{% set response = request.getResponseBody() %}
getResponseHeaders

Gets the headers from the response. An array is returned.

Example

{% set request = _core.request.getObject('http://httpbin.org/get') %}
{% do request.get() %}
{% set responseHeaders = request.getResponseHeaders() %}

Returned data

Below is an example response.

Array
(
    [Connection] => Array
    (
        [0] => keep-alive
    )
    [Server] => Array
    (
        [0] => gunicorn/19.7.1
    )
    [Content-Type] => Array
    (
        [0] => application/json
    )
    [Content-Length] => Array
    (
        [0] => 449
    )
)
getResponseJson

If the request returns a JSON response then this will convert the response body JSON to an array and return that array.

Example

{% set request = _core.request.getObject('https://jsonplaceholder.typicode.com/posts') %}
{% do request.get() %}
{% set response = request.getResponseJson() %}
getResponseXml

If the request returns a XML response then this will convert the response body XML to an array and return that array.

Example

{% set request = _core.request.getObject('http://httpbin.org/xml') %}
{% do request.get() %}
{% set response = request.getResponseXml() %}
hasError

Returns whether or not there was an error sending the request.

Example

{% set request = _core.request.getObject('http://httpbin.org/post') %}
{% do request.addParam('name', 'Bob') %}
{% do request.post() %}
{% if request.hasError() %}
    {{ request.getError()|debug('Error') }}
{% endif %}
head

Sends the request as a HEAD request.

Example

{% set request = _core.request.getObject('http://httpbin.org') %}
{% do request.head() %}
options

Sends the request as an OPTIONS request.

Example

{% set request = _core.request.getObject('http://httpbin.org/get') %}
{% do request.options() %}
patch

Sends the request as a PATCH request.

Example

{% set request = _core.request.getObject('http://httpbin.org/patch') %}
{% do request.addParam('name', 'Bob') %}
{% do request.patch() %}
post

Sends the request as a POST request.

Example

{% set request = _core.request.getObject('http://httpbin.org/post') %}
{% do request.addParam('name', 'Sam') %}
{% do request.post() %}
put

Sends the request as a PUT request.

Example

{% set request = _core.request.getObject('http://httpbin.org/put') %}
{% do request.setBody('content') %}
{% do request.put() %}
send

Sends the request.

Parameter

  • method: (string) (required) The request type. It's strongly recommended to set this. If it's not set then the request is sent as a GET request.
    Allowed values include: 'delete', 'get', 'head','options', 'patch', 'post', or 'put'

Examples

Send a DELETE request

{% set request = _core.request.getObject('http://httpbin.org/delete') %}
{% do request.send('delete') %}

Send a GET request.

{% set request = _core.request.getObject('http://httpbin.org/get') %}
{% do request.send('get') %}

Send a HEAD request.

{% set request = _core.request.getObject('http://httpbin.org') %}
{% do request.send('head') %}

Send an OPTIONS request.

{% set request = _core.request.getObject('http://httpbin.org/get') %}
{% do request.send('options') %}

Send a PATCH request.

{% set request = _core.request.getObject('http://httpbin.org/patch') %}
{% do request.addParam('name', 'Bob') %}
{% do request.send('patch') %}

Send a POST request.

{% set request = _core.request.getObject('http://httpbin.org/patch') %}
{% do request.addParam('name', 'Sam') %}
{% do request.send('post') %}

Send a PUT request.

{% set request = _core.request.getObject('http://httpbin.org/put') %}
{% do request.setBody('content') %}
{% do request.send('put') %}
setAuthentication

Sets the username and password to use as authentication for the request.

Parameters

  • username: (string) (required) The username
  • password: (string) (required) The password
  • type: (string) (optional) The authentication type. Allowed values are: 'basic', 'digest' or 'ntlm'. Defaults to 'basic'.

Example

{% do request.setAuthentication('myuser', 'mypassword') %}

Don't use this method if you're trying to Bearer Authentication. For that type of authentication use the addHeader method.

{% do request.addHeader('Authorization', 'Bearer MY_AUTHORIZATION_TOKEY') %}
setBody

Sets the request body. This is best used if you need to send a single string in the request instead of sending form post parameters.

Parameters

  • body: (string) (required) The request body.

Example

{% do request.setBody('request body here') %}
setJsonBody

Sets the request body as a JSON string. This also sets the header "Content-Type" to be "application/json".

Parameters

  • body: (string) (required) The request body.

Example

{% do request.setJsonBody('myJson') %}

Sometimes in your code you may want to set a variable that holds the JSON string as an object. This method will convert that object to a JSON string.

{% set body = {
   "first_name": "Bob",
   "last_name": "Smith",
   "email": "My Email"
} %}
{% do request.setJsonBody(body) %}

If you were using the request object in a form post process script then you can assign the values from the form submission like this:

{% set body = {
 "first_name": form.fields.firstName.value,
 "last_name": form.fields.lastName.value,
 "email": form.fields.email.value
} %}
{% do request.setJsonBody(body) %}
setRequestIsAjax

Sets the request to be an AJAX request by automatically setting the appropriate header.

Example

{% do request.setRequestIsAjax() %}

 
setUrl

Sets the URL for the request. You would use this if you did not pass the URL when getting the request object from _core.request.getObject().

Parameters

  • url: (string) (required) The URL that the request is for.

Example

{% do request.setUrl('http://www.apisite.com/api') %}

If you need to make another request it's better to get a new request object rather than set a different URL.
setVerifySSL

Sets whether or not to verify the SSL certificate for the request. It is enabled by default.

It's best to leave this enabled. The only reason to disable it is if you absolutely trust the owner of the location you're connecting to and you are having connection issues due to their SSL certificate.

Parameters

  • verify: (bool) (required) Whether or not to verify the SSL certificate.

Example

{% do request.setVerifySSL(false) %}