- Provided Clients
A rest.js client is simply a function that accepts an argument as the request and returns a promise for the response.
Clients are typically extended by wrapping interceptors that wrap the client core behavior providing additional functionality and returning an enriched client.
client = rest.wrap(interceptor);
assert.same(rest, client.skip());See the interceptor docs for more information on interceptors and wrapping.
The provided clients are the root of the interceptor chain. They are responsible for the lowest level mechanics of making requests and handling responses. In most cases, the developer doesn't need to be concerned with the particulars of the client, as the best client for the available environment will be chosen automatically.
rest (src)
The default client is also the main module for the rest.js package. It's not a client implementation, but an alias to the best client for a platform. When running within a browser, the XHR client is used; when running within Node.js, the Node client is used. As other JavaScript environments are supported, the default client will continue to map directly to the most appropriate client implementation.
The default client is used internally when no custom client is configured. There are times, when it's useful to change the default client; such as when the automatic environment sniffing is wrong, or you want to add support for a new environment that rest.js doesn't yet understand. In these cases, you can set, get and reset the default client using the rest.setDefaultClient(client), rest.getDefaultClient() and rest.resetDefaultClient() methods respectively.
While it may be tempting to change the default client for application level concerns, changing the default will impact all consumers. In just about every case, using an Interceptor is preferred.
rest/client/xhr (src)
The default client for browsers. The XHR client utilizes the XMLHttpRequest object provided by many browsers.
Special Properties
| Property | Required? | Default | Description |
|---|---|---|---|
| request.engine | optional | window.XMLHttpRequest | The XMLHttpRequest instance to use |
| request.mixin | optional | none | Additional properties to mix into the XHR object |
Know limitations
The XHR client has the same security restrictions as the traditional XMLHttpRequest object. For browsers that support XHR v1, that means that requests may only be made to the same origin as the web page. The origin being defined by the scheme, host and port. XHR v2 clients have support for Cross-origin Resource Sharing (CORS). CORS enabled clients have the ability to make requests to any HTTP based service assuming the server is willing to participate in the CORS dance.
rest/client/node (src)
The default client for Node.js. The Node client uses the 'http' and 'https' modules.
Node specific settings may be modified via the mixin request property. Adding new certificate authorities to trust or changing the agent pool are rare, but sometimes necessary. See the Node docs for details about supported properties.
Special Properties
| Property | Required? | Default | Description |
|---|---|---|---|
| request.mixin | optional | empty | Additional Node.js only parameters |
rest/client/jsonp (src)
JSONP client for browsers. Allows basic cross-origin GETs via script tags. This client is typically employed via the rest/interceptor/jsonp interceptor. Never used as the default client.
Special Properties
| Property | Required? | Default | Description |
|---|---|---|---|
| request.callback.param | optional | 'callback' | URL parameter that contains the JSONP callback function's name |
| request.callback.prefix | optional | 'jsonp' | common prefix for callback function names as they are placed on the window object |
| request.callback.name | optional | generated | pins the name of the callback function, useful for cases where the server doesn't allow custom callback names. Generally not recommended. |