Types in rest.js are based on duck typing; there are no concrete types that need to be constructed. Any JavaScript object matching the general characterisitc for the type can be used. Most of the properties are defined as optional, so even an empty or undefined object may be valid. Clients and interceptors will provided default values as appropriate.
A request may be represented by either a string or an object. Strings are coerced to an object as soon as they are encountered, where the string's value becomes the value of the path property on the object.
| Property | Required? | Default | Description |
|---|---|---|---|
| method | optional | 'GET' if no entity, 'POST' with entity | HTTP method, commonly GET, POST, PUT, DELETE or HEAD |
| path | optional | empty string | path template with optional path variables |
| params | optional | none | name-value parameters for the path template and query string |
| headers | optional | none | name-value custom HTTP headers to send, in addition to the client provided headers |
| entity | optional | none | HTTP entity, request/response body |
| canceled | provided | n/a | indicates if the request was canceled, defined by the root client |
| cancel | provided | n/a | function that will cancel the request if invoked, defined by the root client |
| originator | provided | n/a | the first client to handle this request in the interceptor chain, defined by the interceptor chain |
Interceptors and clients may define additional properties.
| Property | Description |
|---|---|
| request | the request object as received by the root client |
| raw | the underlying request object, like XMLHttpRequest in a browser |
| status.code | status code of the response (i.e. 200, 404) |
| status.text | status phrase of the response (if available) |
| headers | response headers hash of normalized name, value pairs |
| entity | the response body |
Interceptors and clients may define additional properties.
| Method | Arguments | Return | Description |
|---|---|---|---|
| self | request | Promise for Response | propagates the request retuning a promise for the response |
| skip | none | Client | returns the parent client. Not available for the root client, a client may also elect to not be skipable. |
| chain | interceptor, config (optional) | Client | wraps the client with an interceptor returning the resulting client |
| Method | Arguments | Return | Description |
|---|---|---|---|
| self | parent Client (optional), config (optional) | Client | creates a new client chaining off of the parent client with the provided configuration. |
Both the parent and config arguments are typically optional. The default client is commonly used if a parent client is not specified. An interceptor may require certain config properties, in which case the config object is no longer optional.
| Method | Arguments | Return | Description |
|---|---|---|---|
| read | string | any | reads a response entity as a string converting it into any other type |
| write | any | string | writes a request entity as a string converting it from any other type |