REST resource assets

The REST resource and REST resource JavaScript assets are used to communicate with web services exposing themselves using representational state transfer (REST) methods. This enables content to be retrieved from other REST web services, allowing the posting and modification of data using HTTP get, post, head, put and delete requests. Access to servers is processed through authentication settings with the REST resource OAuth session and OAuth 2-legged assets, allowing access to OAuth secure REST web services.

The REST manager can also cache requests based on the cache settings configured on the Details screen.

The REST functionality only supports requests to HTTP and HTTPS URLs.

REST resource

The Details screen of the REST resource asset allows you to configure the settings for the HTTP request to the external web server(s).

Read the Asset screens documentation for more information about the Status, Future status, Thumbnail, and Details sections.

HTTP request

This section allows you to configure the settings of the HTTP request of the REST resource, including the request method and URL of the target REST web service.

The fields available in this section are as follows:

Method

Select the method of requests made by the REST resource. The methods available are as follows:

Get

This allows you to make a get request. This method is used to retrieve and list the content of a resource.

Post

This allows you to make a post request. This method is used to create and modify the content of a resource (for example, adding data to a field on a custom form). Selecting this request method and clicking Save will display the cache post requests and request body fields, as shown in the figure.

The HTTP request section for a POST request
HEAD

This allows you to make a HEAD request. This method is used to retrieve information from an object, such as its update status, without downloading it.

PUT

This allows you to make a PUT request. This method is used to update and replace the content of a resource. Selecting this request method will display the Request body field.

DELETE

This allows you to make a DELETE request. This method is used to delete the content of a resource. By default, this field is set to GET.

Use HTTP 1.0

Select whether to use HTTP 1.0 for the HTTP request instead of the default HTTP 1.1. This is useful when dealing with advanced configurations with older proxy servers that do not fully support HTTP 1.1.

Cache post requests

Select whether to cache POST requests made by the REST resource. POST requests are usually independent operations that will cause a different outcome with each subsequent use. As a result, it is recommended to be careful when using cache so that POST operations are not unexpectedly repeated, causing undesirable results. This field is only available when making a POST request.

URL(s)

Enter the URL(s) of the REST web services with which you want to communicate. Any number of URLs can be entered in these fields.

Timeout (seconds)

Enter the amount of time in seconds that the REST resource will attempt to communicate with the selected REST web services before returning an error. By default, this field is set to 10 seconds.

Follow redirects

Select whether the request will follow any URL redirection set by the selected URL(s). For example, say the site HTTP://www.example.com redirects to http://www.newexample.com. If this field is selected and the REST resource is set to communicate with the example URL, the request will be redirected to the newexample URL. By default, this field is enabled.

Disable SSL certificate

Select whether to disable SSL certificate verification on HTTP requests. This can be useful in cases where the requesting host is using self-signed certificate verification. By default, this field is disabled, meaning SSL certificate verification will be used.

When connecting to web services that require 2way or mutual SSL authentication, additional fields can be utilized to specify the file paths of the SSL certificate, key, and ca (certificate authority). These fields are outlined below.

SSL certificate filepath

Enter the file path of the SSL certificate for SSL verification.

SSL key filepath

Enter the file path of the private key for SSL verification.

SSL ca filepath

Enter the file path of the certificate authority file for SSL verification.

Cache options

Select how requests made by the REST resource will be cached. By default, this field is set to use HTTP expiry headers. The options available are as follows:

Never cache

The request will not be cached.

Use default expiry

The request will be cached according to the amount of time configured in the default cache expiry (seconds) field (see below).

Use HTTP expiry headers

The request will be cached according to the cache settings of the requested URL.

Matrix will use the system’s cache manager to cache the request made by the REST resource (using the REST manager asset type code). As such, the cache manager must be enabled and configured appropriately for these options to work. Read the Cache manager documentation for more information.
Default cache expiry (seconds)

Enter the amount of time in seconds that the REST resource will be cached before expiring. This field is only used if the cache options field is set to Use default expiry. By default, this field is set to 60 seconds.

Authentication type

Select the authentication type that will be used to access the requested URL. This will allow access to secure REST web services. The options available are as follows:

None

No authentication will be attempted. If the requested URL requires authentication, the request will fail.

HTTP basic

Password authentication will be used. To use this authentication type, select HTTP basic from the drop-down menu and click Save. The username and password authentication fields will be displayed, as shown in the figure.

The HTTP basic authentication type
Matrix cookie passthrough

Authentication will be determined by the session cookie set by Matrix, provided it contains valid authentication information. This cookie will be passed through to the response header of the requested URL.

OAuth

Select this method when communicating with an OAuth secure REST web service. When this option is selected, click Save. An additional field will be displayed, as shown in the figure.

The OAuth authentication type

In this field, select a REST resource OAuth session with the configured OAuth authentication information for the target web service. Read the [OAuth authentication on a REST resource] and [REST resource OAuth 2-legged] sections in this documentation for more information.

By default, this field is set to None.

Digest auth

This option will use digest access authentication on the HTTP request. To use this authentication type, select digest auth from the drop-down menu and click Save. The username and password authentication fields will be displayed, as shown in the figure.

The digest auth authentication type
Request headers

Assemble additional headers to send as the header of the request.

Request body

Assemble additional parameters to send as the body of the request. For example, you could set query parameters on a post request using the example request body shown below.

Query=`%globals_get_query^uppercase%&query1=%globals_get_query1^lowercase%`

This request would set the query and query1 parameters as global keyword replacements, able to be called on the REST web service being communicated with.

Keyword modifiers have also been used to display the query parameter in uppercase and the query1 parameter in lowercase. This field is only available when making a POST or PUT request.

Convert to UTF-8

Select this field to convert the response content of the request to a UTF-8 (8-bit Unicode transformation format) character encoding system. To select the UTF-8 encoding system, select this field and click Save. The Document encoding field will be made available, as shown in the figure.

The document encoding field
Document encoding

Select either auto-detect or a specific character encoding system to convert the response content. The following encoding systems are available:

  • ISO-8859-1

  • ISO-8859-15

  • CP866

  • CP1251

  • CP1252

  • KOI8-R

  • BIG5

  • GB2312

  • BIG5-HKSCS

  • SHIFT_JIS

  • EUC-JP

  • UTF-8

Append query string to the request URL

Select this field to enable query strings passed on the URL of the REST resource to be appended on the URL of the HTTP request.

Forward user information

Select this field to forward user information on the HTTP request. This information can be useful when performing permission checks on the REST web service.

Run test

Select this field and click Save to run a request test. Sample return code will be displayed in this field, as shown in the figure.

An excerpt of the sample code from a run test
Allow keyword replacements

Select whether keyword replacements should be replaced in the REST response. If this option is enabled, Matrix will identify and replace content in the keyword format (wrapped in percent signs). By default, this field is set to No, meaning that this option is disabled.

Allow multiple runs

Select whether multiple runs will be allowed if the REST resource asset is nested more than once on the same page.

If this field is set to Yes, requests will be forced to re-run for each instance of a request on a page. By default, this field is set to No.

Forward response headers

Select whether to forward headers from the REST response. This allows you to pass through objects of an unknown type without alteration. By default, this field is set to No.

Error response

Enter the content that will be displayed if the request returns a client (4xx) or server (5xx) error code. For example, say you have entered the text, this web service cannot be contacted into this field. This error message will be displayed if the REST web service URL returns a client or server error.

REST resource JavaScript

The Details screen of the REST resource JavaScript asset allows you to configure the settings of the HTTP request to the external web server(s) and the JavaScript processing of the response. Read the Asset screens documentation for more information about the Status, Future status, Thumbnail, and Details sections.

HTTP request

This section allows you to configure the settings of the HTTP request of the REST resource, including the request method and URL of the target REST web service.

The fields available in this section are similar to those for a REST resource asset. Read the REST resource [Details screen] section in this documentation for more information on these fields.

JavaScript processing

This section allows you to either select a JS file or documentationally enter JavaScript to determine the content processed by the REST resource JavaScript asset.

Request data is available as JSON data using the pre-defined variable _REST. For example, print(_REST.response.body); will print the body of the first REST web server response.

The fields available in this section are as follows:

Session var name

The response of HTTP response array object can be stored as a custom specified variable in the matrix session sandbox based on the value you put into this field. You can overwrite this array value with a custom one if you print anything using the JavaScript field.

For example, if you enter response in this field and in the JavaScript field you enter print(_REST.response.body), the value of the _REST.response.body will be stored in the session variable, which can then be accessed using a custom session keyword of %globals_session_response%.

This field is only available on the call REST resource form submission action and the call REST resource trigger action.

Pre-process matrix global keywords

Enable this option to allow global keyword replacements (%globals_*%) to be evaluated before run JavaScript.

JS engine

Select the engine to execute JS commands on the REST resource JavaScript asset. By default, this is set to use the v8 JavaScript engine, which requires the PECL v8js extension installed on your system.

Read the PECL v8js package documentation for more information. Alternatively, you can select to use SpiderMonkey, as configured on the External tools configuration screen.

Read the External tools configuration documentation for more information.

Include files

Select a file asset, such as a JS file, within the system for JavaScript processing. To select more than one file, click the More… button. An additional field will appear on the screen. Files selected in this field will be run in sequential order, followed by any code entered in the JavaScript field.

Process keywords in JavaScript files

Files added through the 'included files' field can be individually selected for keyword processing in this section.

JavaScript

Enter valid JavaScript to use for JavaScript processing. Example JavaScript is shown below.

var s = _REST.response.body;
print(s.length);
print(_REST.response.body);

When this JavaScript code is used, the character length of the REST response body is printed, followed by the body content itself.

You can also access and use response error messages and codes returned by the response, for example:

print(_REST.response.error);
print(_REST.response.error_code);

© 2015- Squiz Pty Ltd