HTTP API

class HttpApi(im, opts)

A helper class for making HTTP requests via the HTTP sandbox resource.

Arguments:
  • im (InteractionMachine) – The interaction machine to use when making requests.
  • opts.headers (object) – Default headers to use in HTTP requests.
  • opts.auth (object) – Adds a HTTP Basic authentication to the default headers. Should contain username and password attributes.
static check_reply(reply, method, url, request_body)

Check an HTTP reply and raise an HttpApiError() if the response status code is not in the 200 range or the reply body cannot be decoded.

Logs an error via the sandbox logging resource in an error is raised.

Arguments:
  • reply (object) – Raw response to the sandbox API command.
  • method (string) – The HTTP method used in the request (for use in error messages).
  • url (string) – The URL the HTTP request was made to (for use in error messages).
  • request_body (string) – The body of the HTTP request (for use in error messages).

Returns the decoded response body or raises an HttpApiError().

static create_headers(headers)

Combines a set of custom headers with the default headers passed to HttpApi().

Arguments:
  • headers (object) – Additional HTTP headers. Attributes are header names. Values are header values.

Returns the complete set of HTTP headers.

static decode_response_body(body)
Arguments:
  • body (string) – The body to decode.

Sub-classes should override this to decode the response body and throw an exception if the body cannot be parsed. This base implementation returns the body as-is (i.e. decoding is left to the code calling the HttpApi()).

static delete(url, opts)

Make an HTTP DELETE request.

Arguments:
  • url (string) – The URL to make the request to.
  • opts (object) – Options to pass to HttpApi.request().

Returns a promise which fires with the decoded value of the response body or an object with an error attribute containing the error message.

static encode_request_data(data)
Arguments:
  • data (object) – The data to encode.

Sub-classes should override this to encode the request body and throw an exception if the data cannot be encoded. This base implementation returns the data as-is (i.e. encoding is left to code calling the HttpApi()).

static get(url, opts)

Make an HTTP GET request.

Arguments:
  • url (string) – The URL to make the request to.
  • opts (object) – Options to pass to HttpApi.request().

Returns a promise which fires with the decoded value of the response body or an object with an error attribute containing the error message.

static head(url, opts)

Make an HTTP HEAD request.

Arguments:
  • url (string) – The URL to make the request to.
  • opts (object) – Options to pass to HttpApi.request().

Returns a promise which fires with the decoded value of the response body or an object with an error attribute containing the error message.

static post(url, opts)

Make an HTTP POST request.

Arguments:
  • url (string) – The URL to make the request to.
  • opts (object) – Options to pass to HttpApi.request().

Returns a promise which fires with the decoded value of the response body or an object with an error attribute containing the error message.

static put(url, opts)

Make an HTTP PUT request.

Arguments:
  • url (string) – The URL to make the request to.
  • opts (object) – Options to pass to HttpApi.request().

Returns a promise which fires with the decoded value of the response body or an object with an error attribute containing the error message.

static request(method, url, opts)
Arguments:
  • method (string) – The HTTP method to use (e.g. GET, POST).
  • url (string) – The URL to make the request to. If you pass in query parameters using opts.params, don’t include any in the URL itself.
  • opts.params (object) – Key-value pairs to append to the URL as query parameters.
  • opts.data (object) – Data to pass as the request body. Will be encoded using HttpApi.encode_request_data() before being sent.
  • opts.headers (object) – Additional headers to add to the default headers.

Returns a promise that fires once the request is completed. The value returned by the promise is the body of the response decoded using HttpApi.decode_response_body() or an object containing an attribute named error whose value is the error message.

class HttpApiError(msg)

Thrown when an error occurs while making an HTTP request.

Arguments:
  • msg (string) – a description of the error.
class JsonApi(im, opts)

A helper class for making HTTP requests that send and receive JSON encoded data.

Arguments:
  • im (InteractionMachine) – The interaction machine to use when making requests.
  • opts.headers (object) – Default headers to use in HTTP requests. The Content-Type header is overridden to be application/json; charset=utf-8.
  • opts.auth (object) – Adds a HTTP Basic authentication to the default headers. Should contain username and password attributes.
static decode_response_body(body)

Decode an HTTP response body using JSON.parse().

Arguments:
  • body (string) – Raw HTTP response body to parse.

Returns the decoded response body.

static encode_request_data(data)

Encode an object as JSON using JSON.stringify().

Arguments:
  • data (object) – Object to encode to JSON.

Returns the serialized object as a string.