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 toGET
) -
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 alwaysxhr
) -
payload
- internal-only, preparedbody
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
isapplication/json
(JSON request), the request body will automatically be stringified to JSON, unless it already is a string. -
If the
Content-Type
ismultipart/form-data
, and the request body is an instance of anObject
, the keys/values in the request body will automatically be added to a newFormData
instance, unless the request body already is aFormData
instance, in which case it is used directly. -
If the
Content-Type
isapplication/x-www-form-urlencoded
, and the request body is an instance of anObject
, 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 bemultipart/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
- TheRequest
which was sent -
interface
- The interface object which sent the request (e.g. anXMLHttpRequest
object) -
headers
- key/value object of response headers -
json
- getbodyRaw
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.