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.
  • opts.verify_options (string) – The default list of options to verify when doing HTTPS requests. Optional.
  • opts.ssl_method (string) – The default ssl method to attempt for HTTPS requests. Optional.
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 parse_reply(reply, request)

Check an HTTP reply and throw an HttpRequestError() if the sandbox API command was unsuccessful, or otherwise parse the sandbox’s reply into a response. If the response status code is not in the 200 range or the reply body cannot be decoded, throw an HttpResponseError().

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

Arguments:
  • reply (object) – Raw response to the sandbox API command.
  • request (HttpRequest) – The request that initiated the sandbox API command.

Returns an HttpResponse() or throws an HttpApiError() (either the HttpRequestError() or HttpResponseError() derivative, depending on what error occured).

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 post(url, opts)

Make an HTTP PATCH 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 – An object of key-value pairs to append to the URL as query parameters. Can be in any form accepted by node.js’s querystring module
  • 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 HttpResponse() via a promise. Failures while making and checking the request will be thrown as HttpApiError`s, and can be caught with a Q errback. See :meth:`HttpApi.parse_reply() for more on the response parsing and error throwing.

class HttpApiError()

Thrown when an error occurs while making and checking an HTTP request and the corresponding API reply.

class HttpRequest(request, code, opts)

Encapsulates information about an HTTP request made by the HttpApi(). Once HttpRequest.encode() has been invoked, the request’s data is encoded and made available as the request’s body.

Arguments:
  • method (string) – the HTTP request method.
  • url (string) – the url to send the request to.
  • opts.data (string) – the request’s data to be encoded as the request’s body. Optional.
  • opts.params – An object of key-value pairs to append to the URL as query parameters. Can be in any form accepted by node.js’s querystring module
  • opts.verify_options (string) – A list of options to verify when doing an HTTPS request. Optional.
  • opts.ssl_method (string) – A request for a specific ssl method to be attempted. Optional.
static encode()

Encodes the request data (if available).

static to_cmd()

Returns a sandbox API command that can be used to initiate this request via the sandbox API.

class HttpRequestError(request, reason)

Thrown when an error occurs while making and checking an HTTP request.

Arguments:
  • request (HttpRequest) – the request.
  • reason (string) – the reason for the failure. Optional.
class HttpResponse(request, code, opts)

Encapsulates information about an HTTP response given to the HttpApi(). Once HttpResponse.decode() has been invoked, the response’s body is decoded and made available as the response’s data.

Arguments:
  • request (HttpRequest) – the request that caused the response.
  • code (integer) – the status code for the HTTP response.
  • opts.body (string) – the response’s body to be decoded as the response’s data. Optional.
static decode()

Decodes the responses body (if available).

class HttpResponseError(response, reason)

Thrown when an error response is returned by an HTTP request or if the HTTP response body cannot be parsed.

Arguments:
  • response (HttpResponse) – the response.
  • reason (string) – the reason for the failure. Optional.
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.