Class DS.RESTAdapter

The REST adapter allows your store to communicate with an HTTP server by
transmitting JSON via XHR. Most Ember.js apps that consume a JSON API
should use the REST adapter.

This adapter is designed around the idea that the JSON exchanged with
the server should be conventional.

Success and failure

The REST adapter will consider a success any response with a status code
of the 2xx family ("Success"), as well as 304 ("Not Modified"). Any other
status code will be considered a failure.

On success, the request promise will be resolved with the full response
payload.

Failed responses with status code 422 ("Unprocessable Entity") will be
considered "invalid". The response will be discarded, except for the
errors key. The request promise will be rejected with a DS.InvalidError.
This error object will encapsulate the saved errors value.

Any other status codes will be treated as an "adapter error". The request
promise will be rejected, similarly to the "invalid" case, but with
an instance of DS.AdapterError instead.

JSON Structure

The REST adapter expects the JSON returned from your server to follow
these conventions.

Object Root

The JSON payload should be an object that contains the record inside a
root property. For example, in response to a GET request for
/posts/1, the JSON should look like this:

Note that the object root can be pluralized for both a single-object response
and an array response: the REST adapter is not strict on this. Further, if the
HTTP server responds to a GET request to /posts/1 (e.g. the response to a
findRecord query) with more than one object in the array, Ember Data will
only display the object with the matching ID.

Conventional Names

Attribute names in your JSON payload should be the camelCased versions of
the attributes in your Ember.js models.

If the records in the relationship are not known when the response
is serialized its also possible to represent the relationship as a
url using the links key in the response. Ember Data will fetch
this url to resolve the relationship when it is accessed for the
first time.

Errors

If a response is considered a failure, the JSON payload is expected to include
a top-level key errors, detailing any specific issues. For example:

1
2
3
4
5

{
"errors": {
"msg": "Something went wrong"
}
}

This adapter does not make any assumptions as to the format of the errors
object. It will simply be passed along as is, wrapped in an instance
of DS.InvalidError or DS.AdapterError. The serializer can interpret it
afterwards.

Customization

Endpoint path customization

Endpoint paths can be prefixed with a namespace by setting the namespace
property on the adapter:

Host customization

Headers customization

Some APIs require HTTP headers, e.g. to provide an API key. Arbitrary
headers can be set as key/value pairs on the RESTAdapter's headers
object and Ember Data will send them along with each ajax request.

In some cases, your dynamic headers may require data from some
object outside of Ember's observer system (for example
document.cookie). You can use the
volatile
function to set the property into a non-cached mode causing the headers to
be recomputed with every request.

findMany
(store, type, ids, snapshots)
Promise

Called by the store in order to fetch several records together if coalesceFindRequests is true

For example, if the original payload looks like:

1
2
3
4
5

{
"id": 1,
"title": "Rails is omakase",
"comments": [ 1, 2, 3 ]
}

The IDs will be passed as a URL-encoded Array of IDs, in this form:

1

ids[]=1&ids[]=2&ids[]=3

Many servers, such as Rails and PHP, will automatically convert this URL-encoded array
into an Array for you on the server-side. If you want to encode the
IDs, differently, just override this (one-line) method.

The findMany method makes an Ajax (HTTP GET) request to a URL computed by buildURL, and returns a
promise for the resulting payload.

If the globally unique IDs for your records should be generated on the client,
implement the generateIdForRecord() method. This method will be invoked
each time you create a new record, and the value returned from it will be
assigned to the record's primaryKey.

Most traditional REST-like HTTP APIs will not use this method. Instead, the ID
of the record will be set by the server, and your adapter will update the store
with the new ID when it calls didCreateRecord(). Only implement this method if
you intend to generate record IDs on the client-side.

The generateIdForRecord() method will be invoked with the requesting store as
the first parameter and the newly created record as the second parameter:

groupRecordsForFindMany
(store, snapshots)
Array

an array of arrays of records, each of which is to be
loaded separately by `findMany`.

Organize records into groups, each of which is to be passed to separate
calls to findMany.

This implementation groups together records that have the same base URL but
differing ids. For example /comments/1 and /comments/2 will be grouped together
because we know findMany can coalesce them together as /comments?ids[]=1&ids[]=2

It also supports urls where ids are passed as a query param, such as /comments?id=1
but not those where there is more than 1 query param such as /comments?id=2&name=David
Currently only the query param of id is supported. If you need to support others, please
override this or the _stripIDFromURL method.

It does not group records that have differing base urls, such as for example: /posts/1/comments/2
and /posts/2/comments/3

By default this hook just returns the json payload passed to it.
You might want to override it in two cases:

Your API might return useful results in the response headers.
Response headers are passed in as the second argument.

Your API might return errors as successful responses with status code
200 and an Errors text or object. You can return a DS.InvalidError or a
DS.AdapterError (or a sub class) from this hook and it will automatically
reject the promise and put your record into the invalid or error state.

Returning a DS.InvalidError from this method will cause the
record to transition into the invalid state and make the
errors object available on the record. When returning an
DS.InvalidError the store will attempt to normalize the error data
returned from the server using the serializer's extractErrors
method.

shouldReloadAll
(store, snapshotRecordArray)
Boolean

This method is used by the store to determine if the store should
reload all records from the adapter when records are requested by
store.findAll.

If this method returns true, the store will re-fetch all records from
the adapter. If this method returns false, the store will resolve
immediately using the cached records.

For example, if you are building an events ticketing system, in which users
can only reserve tickets for 20 minutes at a time, and want to ensure that
in each route you have data that is no more than 20 minutes old you could
write:

This method would ensure that whenever you do store.findAll('ticket') you
will always get a list of tickets that are no more than 20 minutes old. In
case a cached version is more than 20 minutes old, findAll will not
resolve until you fetched the latest versions.

By default this methods returns true if the passed snapshotRecordArray
is empty (meaning that there are no records locally available yet),
otherwise it returns false.

Note that, with default settings, shouldBackgroundReloadAll will always
re-fetch all the records in the background even if shouldReloadAll returns
false. You can override shouldBackgroundReloadAll if this does not suit
your use case.

shouldReloadRecord
(store, snapshot)
Boolean

This method is used by the store to determine if the store should
reload a record from the adapter when a record is requested by
store.findRecord.

If this method returns true, the store will re-fetch a record from
the adapter. If this method returns false, the store will resolve
immediately using the cached record.

For example, if you are building an events ticketing system, in which users
can only reserve tickets for 20 minutes at a time, and want to ensure that
in each route you have data that is no more than 20 minutes old you could
write:

This method would ensure that whenever you do store.findRecord('ticket',
id) you will always get a ticket that is no more than 20 minutes old. In
case the cached version is more than 20 minutes old, findRecord will not
resolve until you fetched the latest version.

By default this hook returns false, as most UIs should not block user
interactions while waiting on data update.

Note that, with default settings, shouldBackgroundReloadRecord will always
re-fetch the records in the background even if shouldReloadRecord returns
false. You can override shouldBackgroundReloadRecord if this does not
suit your use case.