Accessor: net/REST

net/REST

Accessor for RESTful interfaces. Upon receipt of a trigger input, this accessor will issue an HTTP request specified by the inputs. Some time later, the accessor will receive a response from the server or a timeout. In the first case, the accessor will produce the response (body, status code, and headers) on output ports. In the second case, it will produce a nil output on the response port and an error.

The accessor does not block waiting for the response, but any additional triggered requests will be queued to be issued only after the pending request has received either a response or a timeout. This strategy ensures that outputs from this accessor are produced in the same order as the inputs that trigger the HTTP requests.

The options input can be a string URL (with surrounding quotation marks) or an object with the following fields:

  • headers: An object containing request headers. By default this is an empty object. Items may have a value that is an array of values, for headers with more than one value.
  • keepAlive: A boolean that specified whether to keep sockets around in a pool to be used by other requests in the future. This defaults to false.
  • method: A string specifying the HTTP request method. This defaults to 'GET', but can also be 'PUT', 'POST', 'DELETE', etc.
  • url: A string that can be parsed as a URL, or an object containing the following fields:
    • host: A string giving the domain name or IP address of the server to issue the request to. This defaults to 'localhost'.
    • protocol: The protocol. This is a string that defaults to 'http'.
    • port: Port of remote server. This defaults to 80.

For example, the options parameter could be set to {"headers":{"Content-Type":"application/x-www-form-urlencoded"}, "method":"POST", "url":"..."}

In addition, there is a command input that is a string that is appended as a path to the URL constructed from the options input. This defaults to the empty string.

The arguments input an object with fields that are converted to a query string to append to the url, for example '?arg=value'. If the value contains characters that are not allowed in a URL, such as spaces, they will encoded according to the ASCII standard, see http://www.w3schools.com/tags/ref_urlencode.asp .

A trigger input triggers invocation of the current command. Any value provided on the trigger input is ignored.

The output response will be a string if the MIME type of the accessed page begins with "text". If the MIME type begins with anything else, then the binary data will be produced. It is up to the host implementation to ensure that the data is given in some form that is usable by downstream accessors or actors.

The parameter 'timeout' specifies how long this accessor will wait for response. If it does not receive the response by the specified time, then it will issue a null response output and an error event (calling the error() function of the host).

If the parameter 'outputCompleteResponseOnly' is true (the default), then this accessor will produce a 'response' output only upon receiving a complete response. If it is false, then multiple outputs may result from a single input or trigger.

Version:
  • $$Id$$
Author:
  • Edward A. Lee (eal@eecs.berkeley.edu), contributor: Christopher Brooks
Source:
Inputs:
Name Type Description
options JSON The url for the command or an object specifying options.
command string The command.
arguments JSON Arguments to the command.
body The request body, if any. This supports at least strings and image data.
trigger An input to trigger the command.
Outputs:
Name Type Description
response string The server's response.
status string The status code and message of the response.
headers The headers sent with the response.
Parameters:
Name Type Description
timeout int The amount of time (in milliseconds) to wait for a response before triggering a null response and an error. This defaults to 5000.
outputCompleteResponseOnly boolean If true (the default), the produce a 'response' output only upon receiving the entire response.

Methods

(static) encodePath()

Build the path from the command and arguments. This default implementation returns 'command?args', where args is an encoding of the arguments input for embedding in a URL. For example, if the arguments input is the object { foo: 'bar', baz: ['qux', 'quux'], corge: '' } then the returned string will be command?foo=bar&baz=qux&baz=quux&corge= Derived accessors may override this function to customize the interaction. The returned string should not include a leading '/'. That will be added automatically.

Source:

(static) filterResponse(response)

Filter the response. This base class just returns the argument unmodified, but derived classes can override this to extract a portion of the response, for example. Note that the response argument can be null, indicating that there was no response (e.g., a timeout or error occurred).

Parameters:
Name Type Description
response

The response, or null if there is none.

Source:

(static) handleError(message)

Handle an error.

Parameters:
Name Type Description
message

The error message.

Source:

(static) handleResponse(message)

Handle the response from the RESTful service. The argument is expected to be be an instance of IncomingMessage, defined in the httpClient module. This base class extracts the body field of the message, if there is one, and produces that on the 'response' output, and otherwise just produces the message on the output. If the argument is null or undefined, then do nothing.

Parameters:
Name Type Description
message

An incoming message.

Source:

(static) initialize()

Register the input handler.

Source:

(static) issueCommand(callback)

Issue the command based on the current value of the inputs. This constructs a path using encodePath and combines it with the url input to construct the full command.

Parameters:
Name Type Description
callback

The callback function that will be called with the response as an argument (an instance of IncomingMessage, defined in the httpClient module).

Source:

(static) setup()

Define inputs and outputs.

Source:

(static) stopPendingRequest()

Stop a request in progress. A derived class may connect to a server that doesn't end the connection after sending this accessor the complete response. To avoid unecessary timeouts, the derived class may use this function. For example:

exports.handleResponse = function(message){ exports.ssuper.handleResponse.call(this, message); exports.ssuper.stopPendingRequest.call(this); };

Source:

(static) wrapup()

Upon wrapup, stop handling new inputs.

Source: