Request

AmplifyJS API Documentation core/amplify.core.js

amplify.request

amplify.request is an abstraction layer that can be used for any kind of request for data.
amplify.request sets out to separate the data retrieval and caching mechanisms from data requestors.

Using the amplify.request.define function you can create and maintain
your entire server interface and caching policy in a single place,
reducing the impact of any server interface changes. Components that
need data can retrieve the data through amplify.request without
concern for data caching, server interface, resource location,
data types, wrappers, and all the other specificities of the
client/server interaction.

Requests made through amplify.request will always be resolved asynchronously,
even if the resource invokes the callbacks immediately.
This ensures that you will never having timing problems if the request definition is changed in the future.

Just getting started? Take a look at the examples section
below for a few of the popular use cases with amplify.request.

NOTE:amplify.request depends on the use of jQuery 1.4 or higher when the ajax request type is used.

resource: Function to handle requests. Receives a hash with the following properties:

resourceId: Identifier string for the resource.

data: Data provided by the user.

success: Callback to invoke on success.

error: Callback to invoke on error.

Request Types

Built-in Types

amplify.request comes with a built-in ajax type.

NOTE: The ajax request type depends on the use of jQuery 1.4 or higher.

Custom Types

You can choose to create additional types by adding to the amplify.request.types hash.
There is also an option to define custom one-off types for single requests.

Data Handling

Pre-defined Data

When defining an ajax request, you can provide data in the definition.
This data will be merged (via a deep extend) with any data provided with the request.
Data provided with the request will override data provided in the definition.

Data Mapping

Data maps allow you to modify the data for an ajax request before the data is sent.
You can use a hash to map keys or you can use a function for complete flexibility.

URL substitution/routing

You can define variables in the URL of an ajax request by wrapping the variable in curly braces, e.g., "/user/{id}".
The variable will be replaced by the respective value from the data provided in the request.
Whenever a variable is replaced, the value is removed from the data (not submitted as GET/POST data).
If there are variables that are not replaced, they will remain in the URL.

Decoders

Decoders allow you to parse an ajax response before calling the success or error callback.
This allows you to return data marked with a status and react accordingly.
This also allows you to manipulate the data any way you want before passing the data along to the callback.

Cache

In-memory Cache

There is a built-in memory cache. You can pass a boolean to enable caching of a request, e.g., cache: true.
You can also pass a number to specify that the response should be cached for a certain amount of time.
For example, cache: 30 will cache the response for 30 milliseconds.

cache: boolean Cache the data in memory for the remainder of this page load.

cache: number Cache the data in memory for the specified number of milliseconds.

Named Caches

cache: string Cache the data using a pre-defined caching mechanism.

cache: {
type: string,
expires: number
}

Cache the data using a pre-defined caching mechanism for the specified number
of milliseconds.

Persistent Client-side Cache

You can also persist a cache if amplify.store has been loaded.
You can specify cache: "persist" to cache in the default store
or you can specify any of the specific stores available, e.g., cache: "localStorage".
You can also use the hash form listed above to store in a persistent cache with
an expiration.

Note: You must include amplify.store.js before amplify.request.js to use persistent caches.

Custom Cache

You can also create additional cache types by adding to the amplify.request.cache hash.

With the success callback, the only default status is success.
With the error callback two default statuses are possible: error and
abort.

Status Codes and Decoders

When specifying a custom decoder for request definition a status code
will be passed in as a parameter. You can determine results from a request based on
this status. When a success or error callback is executed, the
appropriate status will be set by amplify.request.

Statuses with jsend

The jsend request type has an extra default status. The jsend
spec includes a fail status. If a
jsend fail occurs, the error callback ( and appropriate error
subscriptions ) will be called with a status of fail.

Customizing statuses

When calling a success or error callback through a decoder you can
specify a custom status to be sent to the callback as the second
parameter for the callback function.