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
andpassword
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 anHttpResponseError()
.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 anHttpApiError()
(either theHttpRequestError()
orHttpResponseError()
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 asHttpApiError`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()
. OnceHttpRequest.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()
. OnceHttpResponse.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 beapplication/json; charset=utf-8
. - opts.auth (object) – Adds a HTTP Basic authentication to the default headers. Should
contain
username
andpassword
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.