DS.JSONAPIAdapter

The JSONAPIAdapter is the default adapter used by Ember Data. It is responsible for transforming the store's requests into HTTP requests that follow the JSON API format.

JSON API Conventions

The JSONAPIAdapter uses JSON API conventions for building the url for a record and selecting the HTTP verb to use with a request. The actions you can take on a record map onto the following URLs in the JSON API adapter:

Action HTTP Verb URL
store.findRecord('post', 123) GET /posts/123
store.findAll('post') GET /posts
Update postRecord.save() PATCH /posts/123
Create store.createRecord('post').save() POST /posts
Delete postRecord.destroyRecord() DELETE /posts/123

Success and failure

The JSONAPIAdapter 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.

Endpoint path customization

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

1
2
3
4
5
import DS from 'ember-data';

export default DS.JSONAPIAdapter.extend({
  namespace: 'api/1'
});

Requests for the person model would now target /api/1/people/1.

Host customization

An adapter can target other hosts by setting the host property.

1
2
3
4
5
import DS from 'ember-data';

export default DS.JSONAPIAdapter.extend({
  host: 'https://api.example.com'
});

Requests for the person model would now target https://api.example.com/people/1.