senselogic.sitevision.api.script

Interface Requester<O,F>

Type Parameters:

O - script object

F - script function

All Known Subinterfaces:

RequesterChainable<O,F>

@Requireable(value={"Requester","JsonRequester"})
public interface Requester<O,F>

Script utility for handling data (typically JSON) from an external website.

This utility supports the official (RFC2616 and RFC5789) request methods: GET, POST, HEAD, PUT, DELETE and PATCH - but not the OPTIONS, TRACE or CONNECT methods. Redirects will only be followed for the GET and HEAD methods.

URL:s with an international domain name (IDN) will be converted (ACE:d) automatically internally by this utility, e.g. invoking get("http://www.ringsjömingel.se") will do a HTTP GET using "http://www.xn--ringsjmingel-9ib.se".

Requester Options

Each supported method in this utility comes in two flavours: a base method with the URL only (see example above) and a method that also allows additional options. These are the supported options:

Request options

• data (key/value) - request payload/parameters.
• contentType (string) - request data type (default is "application/x-www-form-urlencoded").
  • "text/plain" - data will be sent as a string entity
  • "application/json" - data will be sent as JSON
    • When the targeted API expects "application/vnd.api+json", you should set the "contentType" option to "application/json" while ensuring that the headers options include the expected "Content-Type"
  • "multipart/form-data" [@since Sitevision 4.5.4] - request will be sent as multipart form entity
• headers (key/value) - request headers. Note that if no "Content-Type" header is explicitly stated, it will be set to a value indicated by the contentType option.
• username (string) - the username to use for authentication.
• password (string) - the password to use for authentication.
• preemptiveAuthentication (boolean) - whether or not to do a preemptive BASIC authentication (default is false).
• files (key/value) [@since Sitevision 4.5.4] - files to include when using "multipart/form-data" as contentType. Value must be a Node of type sv:file, sv:temporaryFile or sv:image.
• retry (boolean) [@since Sitevision 7] - whether or not to retry when request fails with status code 429 or 503 (i.e. "Too many requests" or "Service unavailable") (default is false).
• retryCount (integer) [@since Sitevision 7] - number of retry attempts (only applicable when the retry option is used). Value should be between 1 and 6, values outside range will use nearest value within range. (default is 1).
• oauth2 (sv:oAuth2Configuration) [since Sitevision 7] - what oAuth2Configuration to use when appending OAuth2 access tokens to requests
• oauth2Type (string) [since Sitevision 7] - type of OAuth2 request (default is "user")
  • "user" - Perform request with an access token representing the current user
  • "app" - Perform request with an access token representing the sv:oAuth2Configuration

Response options

• dataType (string) - response data type (default is "json").
  • "json" - response body will be parsed as JSON
  • "xml" - response body will be converted to and parsed as JSON
  • "text" [@since Sitevision 4.2.3] - response body will be as-is (i.e. plain text string)
  • "file" [@since Sitevision 4.5.5] - response body will be a binary file wrapped as a sv:temporaryFile
• fallbackCharset (string) [@since Sitevision 5.1.1] - what charset to use when processing the response from the remote system if there are no charset specified in the response (default is "UTF-8").

Some methods have additional options. Consult the documentation of the specific method.

Basic JSON GET example

Below is a example of how to use the Requester utility to execute a basic GET and process the JSON response body.

   require('Requester')
       .get('http://jsonplaceholder.typicode.com/posts')
       .done(function(result) {
          // GET succeeded, handle JSON response result
          var i, count = result.length, item;
          for (i = 0; i < count; i++) {
             item = result[i];
             out.println(item.id + ' - ' + item.title + '<br>');
             out.println('<small>' + item.body + '</small><br>');
          }
       })
       .fail(function(message) {
          // GET failed, handle error message
          out.println(message);
       });

GET and POST examples with options

Below is another example that also demonstrates the options usage and further callback arguments.

   var requester = require('Requester'),
       options = {
          username: 'thomas',
          password: 'nordahl_123',
          preemptiveAuthentication: true,
          headers: {
             'X-custom-header': 'Custom value'
          },
          data: {
             query: 'football',
             category: 'all'
          }
       },
       multipartOptions = {
          contentType: 'multipart/form-data',
          files: {
             file: fileNode // sv:file, sv:temporaryFile or sv:image
          },
          data: {
             name: 'foo'
          }
       };

    requester.get('https://arestfulsite.se/endpoint/requires/authentication/search', options)
       .done(function(result, statusCode, headers) {
          // GET succeeded, handle potential JSON response result appropriately
          if (statusCode === 204) {
             ...
          } else {
             ...
          }
          ...
       })
       .fail(function(message, status) {
          // GET failed, handle appropriately
          if (status.statusCode === 401) {
             ...
          }
          if (status.headers) {
             ...
          }
          if (status.body) {
             ...
          }
          ...
       });

       requester.post('https://arestfulsite.se/endpoint', multipartOptions)
       ...

Example of how to POST XML

To send XML as a string entity, you must set the contentType option to "text/plain". You should typically also set the Content-Type header to an appropriate value that the remote system will accept. (Remember - if no Content-Type header is set, Requester will fallback to the type indicated by the contentType option - i.e. "text/plain" in this case).

   var requester = require('Requester'),
       options = {
          dataType: 'text',
          contentType: 'text/plain',
          headers: {
             'Content-Type': 'application/xml; charset=UTF-8'
          },
          data: '<?xml version="1.0" encoding="UTF-8"?><message>Hello backend system</message>'
       };

    requester.post('https://xmlsite.se/endpoint', options)
       .done(function(result, statusCode, headers) {
          // POST succeeded, handle XML string response result appropriately
          ...
       })
       .fail(function(message, status) {
          // POST failed, handle appropriately
          ...
       });

Tip! Use XmlParserUtil to process the XML response string!

Example of how to make OAuth2 requests

To make a request to a protected resource URL, you must set the oauth2 option to a valid sv:oAuth2Configuration. Special considerations must be made regarding error handling. See error handling below.

Perform OAuth2 request as user

   var requester = require('Requester'),
       oAuth2Configuration = (...),
       options = {
          oauth2: oAuth2Configuration
       };

    requester.get('https://resourceserver.com/protected-endpoint', options)
       .done(function(result, statusCode, headers) {
          // Request succeeded, handle response appropriately
          ...
       })
       .fail(function(message, status) {
          // Request failed, handle appropriately
          ...
       });

Perform OAuth2 request as application

   var requester = require('Requester'),
       oAuth2Configuration = (...),
       options = {
          oauth2: oAuth2Configuration,
          oauth2Type: 'app'
       };

    requester.get('https://resourceserver.com/protected-endpoint', options)
       .done(function(result, statusCode, headers) {
          // Request succeeded, handle response appropriately
          ...
       })
       .fail(function(message, status) {
          // Request failed, handle appropriately
          ...
       });

OAuth2 error handling

Different resource servers returns errors in different format. However, a few common error situations might occur in every single request and needs proper handling for a smooth user experience.

• No access token - The user must be redirected to obtain an access token
• Insufficient scope - The user must be redirected to obtain the required scope
• Expired access token (and refresh token) - The user must be redirected to obtain a new access token
• User denied the authorize request - Inform the user why the app needs access to the users resources

Tip! Use OAuth2 requireable util to perform OAuth2 operations.

HTTP Connections

Note that outgoing socket connections is a shared (and limited) server resource! All requests will be handled by connections that comes from a shared http connection pool. The pool has a fixed number of connections (typically 100) and specified timeouts (typically 5 seconds). A request will fail if a connection can not be made at all (exhausted pool) or if the external website doesn't respond in time (request timeout). A failure is typically handled via RequesterChainable.fail(Object).

Important Requireable note! "JsonRequester" is available in all Sitevision versions since 4.2 but "Requester" was introduced as of Sitevision 4.5.5.

REST siblings note!

• Server-side invoke of the local Sitevision REST API should typically be handled via RestApi.
• Server-side invoke of a local RESTApp should typically be handled via RestAppInvoker.

Since:

Sitevision 4.2

Author:

Magnus Lövgren

See Also:

RestApi, RestAppInvoker

Method Summary

Modifier and Type	Method and Description
RequesterChainable<O,F>	delete(String aURL) Execute a HTTP DELETE.
RequesterChainable<O,F>	delete(String aURL, O aOptions) Execute a HTTP DELETE with options.
RequesterChainable<O,F>	get(String aURL) Execute a HTTP GET.
RequesterChainable<O,F>	get(String aURL, O aOptions) Execute a HTTP GET with options.
RequesterChainable<O,F>	head(String aURL) Execute a HTTP HEAD.
RequesterChainable<O,F>	head(String aURL, O aOptions) Execute a HTTP HEAD with options.
RequesterChainable<O,F>	patch(String aURL) Execute a HTTP PATCH.
RequesterChainable<O,F>	patch(String aURL, O aOptions) Execute a HTTP PATCH with options.
RequesterChainable<O,F>	post(String aURL) Execute a HTTP POST.
RequesterChainable<O,F>	post(String aURL, O aOptions) Execute a HTTP POST with options.
RequesterChainable<O,F>	put(String aURL) Execute a HTTP PUT.
RequesterChainable<O,F>	put(String aURL, O aOptions) Execute a HTTP PUT with options.

Method Detail

get

RequesterChainable<O,F> get(String aURL)

Execute a HTTP GET.

Parameters:

aURL - the url

Returns:

a chainable requester

get

RequesterChainable<O,F> get(String aURL,
                            O aOptions)

Execute a HTTP GET with options.

Parameters:

aURL - the url

aOptions - the options, see options example above

Returns:

a chainable requester

put

RequesterChainable<O,F> put(String aURL)

Execute a HTTP PUT.

Parameters:

aURL - the url

Returns:

a chainable requester

put

RequesterChainable<O,F> put(String aURL,
                            O aOptions)

Execute a HTTP PUT with options.

Parameters:

aURL - the url

aOptions - the options, see options example above

Returns:

a chainable requester

post

RequesterChainable<O,F> post(String aURL)

Execute a HTTP POST.

Parameters:

aURL - the url

Returns:

a chainable requester

post

RequesterChainable<O,F> post(String aURL,
                             O aOptions)

Execute a HTTP POST with options.

Parameters:

aURL - the url

aOptions - the options, see options example above

Returns:

a chainable requester

delete

RequesterChainable<O,F> delete(String aURL)

Execute a HTTP DELETE.

Parameters:

aURL - the url

Returns:

a chainable requester

delete

RequesterChainable<O,F> delete(String aURL,
                               O aOptions)

Execute a HTTP DELETE with options.

aOptions extension for delete

• deleteOptions (key/value) [@since Sitevision 4.5.3] - options for delete
  • sendDataAsBody (boolean) - send data in the request body

Parameters:

aURL - the url

aOptions - the options, see options example above

Returns:

a chainable requester

patch

RequesterChainable<O,F> patch(String aURL)

Execute a HTTP PATCH.

Note! The RFC5789 PATCH method is neither safe nor idempotent as defined by RFC2616.

Parameters:

aURL - the url

Returns:

a chainable requester

Since:

Sitevision 7.2.3

patch

RequesterChainable<O,F> patch(String aURL,
                              O aOptions)

Execute a HTTP PATCH with options.

Note! The RFC5789 PATCH method is neither safe nor idempotent as defined by RFC2616.

Parameters:

aURL - the url

aOptions - the options, see options example above

Returns:

a chainable requester

Since:

Sitevision 7.2.3

head

RequesterChainable<O,F> head(String aURL)

Execute a HTTP HEAD.

Note! The response of a HEAD request does not have a body.

Parameters:

aURL - the url

Returns:

a chainable requester

Since:

Sitevision 7.2.3

head

RequesterChainable<O,F> head(String aURL,
                             O aOptions)

Execute a HTTP HEAD with options.

Note! The response of a HEAD request does not have a body.

Parameters:

aURL - the url

aOptions - the options, see options example above

Returns:

a chainable requester

Since:

Sitevision 7.2.3