- 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 chaining interceptors that wrap the client core behavior providing additional functionality and returning an enriched client.
client = rest.chain(interceptor);
assert.same(rest, client.skip());See the interceptor docs for more information on interceptors and chaining.
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 implementations, 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.
rest/client/xhr (src)
The default client for browsers. The XHR client utilizes the XMLHttpRequest object provided by many browsers. Most every browser has direct support for XHR today. The rest/interceptor/ie/xhr interceptor can provided fall back support for older IE without native XHR.
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.
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. |
rest/client/xdr (src)
Cross-origin support available within IE, in particular IE 8 and 9. This client is typically employed via the rest/interceptor/ie/xdomain interceptor. Never used as the default client.
Know limitations
- only GET and POST methods are available
- must use same scheme as origin http-to-http, https-to-https
- no headers, request or response (the response Content-Type is available)
- no response status code