ilm-requests

requesty

Requesty is a lightweight JavaScript requests library.

It's intended for use when making simple requests to external domains.

A limited set of configuration options are supported, including the URI base and default headers to use for all requests.

Get started

The Requesty entrypoint has three exports:

• main - Requesty main instance (default)
• config - Configuration store, used by default for all requests if none other specified per-request
• Request - Request class, used to make new requests.

Creating a request

Instantiate a new Request object.

You must pass the URL as the first constructor argument, with the method optionally second (defaults to GET).

You can set the following optional properties:

• url - URL (will be resolved relative to configuration base if enabled)
• method - Method to use (defaults to GET)
• headers - Headers to add to request, as key/value object
• body - Body data to add to request, as key/value object
• interface - Interface to use to make the request (for now this is always xhr)
• payload - internal-only, prepared body to send as the payload.

Methods

• constructor(url, method="GET") - new request
• addBodyKey(key, value) - add a new body key; throws if already set
• setBodyKey(key, value) - set a body key, overwrites if already set
• getBodyValue(key) - get the value of a body key
• bodyKeySet(key) - get whether a body key is set
• addHeader(header, value) - add a new header; throws if already set
• setHeader(header, value) - set a header, overwrites if already set
• getHeader(header) - get a header value
• headerSet(header) - get whether a header is set

Request bodies

The body of your request will be automatically transformed as required upon making the request, depending on the contents of the Content-Type header in your request.

The following rules are followed:

• If the Content-Type is application/json (JSON request), the request body will automatically be stringified to JSON, unless it already is a string.
• If the Content-Type is multipart/form-data, and the request body is an instance of an Object, the keys/values in the request body will automatically be added to a new FormData instance, unless the request body already is a FormData instance, in which case it is used directly.
• If the Content-Type is application/x-www-form-urlencoded, and the request body is an instance of an Object, the keys/values in the request body will be automatically stringified as a URL-encoded string (i.e. ?key=value&key2=value2); otherwise, the request body will be used directly.
• For all other content types, the request body is used directly (without transformation).
• When the Content-Type header is not set, the content type is presumed to be multipart/form-data and the corresponding rules above apply (to maintain backwards compatibility with v1.1.x of this library).

Making a request

Call request(request, conf=null) on the Requesty main export, passing a Request as the first argument.

Returns a Promise which resolves and returns a Response (or a RequestError) when complete.

You may also use the req(url, request={}, config=null) method on the Requesty main export to create and send a request and get a response without manually creating a Request object; to specify request properties, such as method, body and headers, define them in the request options object – this object is assigned directly to the request object, so set properties as for the Request class.

With both the above endpoints, if you pass an object to the conf parameter, the default configuration in config will be overridden in its entirety with the configuration values in conf.

Errors

A RequestError is returned (extending Error) when the request was made but failed to complete successfully. You can access the request HTTP status code through the status property; message contains the associated HTTP status message.

Responses

The Response object has the following properties:

• body - Body data from response (response when XHR)
• bodyRaw - Raw, unfiltered body data (responseText when XHR)
• type - response type (responseType when XHR)
• status - HTTP status code
• message - HTTP status message
• request - The Request which was sent
• interface - The interface object which sent the request (e.g. an XMLHttpRequest object)
• headers - key/value object of response headers
• json - get bodyRaw parsed from JSON

Methods

• getHeader(header) - get the value of a response header
• headerSet(header) - get whether a header is set

Configuration

You can set configuration globally with the config export or using per-request config objects passed directly to request(...).

The following configuration keys are available:

• urlBase - base URL, to prepend to request URLs if not already absolute (contain a :// base) ("")
• urlBaseEnabled - enable base URL prepend to request URLs which are not already absolute (true)
• defaultHeaders - key/value object of headers to apply to all requests (will be merged with per-request headers) ({})
• defaultHeadersEnabled - enable use of default headers (true)

Defaults from global configuration will be used when no per-request configuration is supplied.

Methods

The global configuration object has the following methods:

• addHeader(header, value) - add a new default header; throws if already exists
• setHeader(header, value) - set a default header value, overwrites if already exists
• getHeader(header) - get a default header value
• headerSet(header) - get whether a header is set.

(End of documentation).

©James Walker 2019. Licensed under the MIT License.