Class DS.JSONAPIAdapter

Extends: DS.RESTAdapter
Defined in: addon/adapters/json-api.js:13
Module: ember-data
Since: v1.13.0

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:

app/adapters/application.js 
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.

app/adapters/application.js 
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.

Show:

coalesceFindRequests

Module: ember-data

Defined in addon/adapters/json-api.js:194

By default the JSONAPIAdapter will send each find request coming from a store.find or from accessing a relationship separately to the server. If your server supports passing ids as a query string, you can set coalesceFindRequests to true to coalesce all find requests within a single runloop.

For example, if you have an initial payload of:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  data: {
    id: 1,
    type: 'post',
    relationship: {
      comments: {
        data: [
          { id: 1, type: 'comment' },
          { id: 2, type: 'comment' }
        ]
      }
    }
  }
}

By default calling post.get('comments') will trigger the following requests(assuming the comments haven't been loaded before):

1
2

GET /comments/1
GET /comments/2

If you set coalesceFindRequests to true it will instead trigger the following request:

1

GET /comments?filter[id]=1,2

Setting coalesceFindRequests to true also works for store.find requests and belongsTo relationships accessed within the same runloop. If you set coalesceFindRequests: true

1
2

store.findRecord('comment', 1);
store.findRecord('comment', 2);

will also send a request to: GET /comments?filter[id]=1,2

Note: Requests coalescing rely on URL building strategy. So if you override buildURL in your app groupRecordsForFindMany more likely should be overridden as well in order for coalescing to work.

coalesceFindRequests

Module: ember-data

Inherited from DS.Adapter addon/adapter.js:427

By default the store will try to coalesce all fetchRecord calls within the same runloop into as few requests as possible by calling groupRecordsForFindMany and passing it into a findMany call. You can opt out of this behaviour by either not implementing the findMany hook or by setting coalesceFindRequests to false.

defaultSerializer

Module: ember-data

Inherited from DS.Adapter addon/adapter.js:65

If you would like your adapter to use a custom serializer you can set the defaultSerializer property to be the name of the custom serializer.

Note the defaultSerializer serializer has a lower priority than a model specific serializer (i.e. PostSerializer) or the application serializer.

app/adapters/django.js 
1
2
3
4
5

import DS from 'ember-data';

export default DS.Adapter.extend({
  defaultSerializer: 'django'
});

headers

Module: ember-data

Inherited from DS.RESTAdapter addon/adapters/rest.js:435

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. For dynamic headers see headers customization.

app/adapters/application.js 
1
2
3
4
5
6
7
8

import DS from 'ember-data';

export default DS.RESTAdapter.extend({
  headers: {
    'API_KEY': 'secret key',
    'ANOTHER_HEADER': 'Some header value'
  }
});

host

Module: ember-data

Inherited from DS.RESTAdapter addon/adapters/rest.js:418

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

app/adapters/application.js 
1
2
3
4
5

import DS from 'ember-data';

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

Requests for the Post model would now target https://api.example.com/post/.

namespace

Module: ember-data

Inherited from DS.RESTAdapter addon/adapters/rest.js:400

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

app/adapters/application.js 
1
2
3
4
5

import DS from 'ember-data';

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

Requests for the Post model would now target /api/1/post/.