Class 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 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 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 it's 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 InvalidError or 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:

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.