Class <Interface> Adapter

public

⚠️ This is LEGACY documentation for a feature that is no longer encouraged to be used. If starting a new app or thinking of implementing a new adapter, consider writing a Handler instead to be used with the RequestManager

The following documentation describes the methods an adapter should implement with descriptions around when an application might expect these methods to be called.

Methods that are not required are marked as optional.

Show:

store
Store

The store service that initiated the request being normalized

schema
ModelSchema

An object with methods for accessing information about the type, attributes and relationships of the primary type associated with the request.

snapshot
Snapshot
returns
Promise

a promise resolving with resource data to feed to the associated serializer

adapter.createRecord takes a request to create a resource of a given type and should return a Promise which fulfills with data for the newly created resource.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to createRecord, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing data for the record.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

If the adapter rejects or throws an error the record will enter an error state and the attributes that had attempted to be saved will still be considered dirty.

InvalidErrors

When rejecting a createRecord request due to validation issues during save (typically a 422 status code), you may throw an InvalidError.

Throwing an InvalidError makes per-attribute errors available for records to use in the UI as needed. Records can also use this information to mark themselves as being in an invalid state. For more reading see the RecordData Errors RFC

let error = new Error(errorMessage);

// these two properties combined
// alert EmberData to this error being for
// invalid properties on the record during
// the request
error.isAdapterError = true;
error.code = 'InvalidError';

// A JSON:API formatted array of errors
// See https://jsonapi.org/format/#errors
error.errors = [];

throw error;
store
Store

The store service that initiated the request being normalized

schema
ModelSchema

An object with methods for accessing information about the type, attributes and relationships of the primary type associated with the request.

snapshot
Snapshot

A Snapshot containing the record's current data

returns

adapter.deleteRecord takes a request to delete a resource of a given type and should return a Promise which resolves when that deletion is complete.

Usually the response will be empty, but you may include additional updates in the response. The response will be fed to the associated serializer's normalizeResponse method with the requestType set to deleteRecord, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing data.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

If the adapter rejects or errors the record will need to be saved again once the reason for the error is addressed in order to persist the deleted state.

In some situations the adapter may need to perform cleanup when destroyed, that cleanup can be done in destroy.

If not implemented, the store does not inform the adapter of destruction.

store
Store

The store service that initiated the request being normalized

schema
ModelSchema

An object with methods for accessing information about the type, attributes and relationships of the primary type associated with the request.

sinceToken
Null

This parameter is no longer used and will always be null.

snapshotRecordArray
SnapshotRecordArray

an object containing any passed in options, adapterOptions, and the ability to access a snapshot for each existing record of the type.

returns
Promise

a promise resolving with resource data to feed to the associated serializer

adapter.findAll takes a request for resources of a given type and should return a Promise which fulfills with a collection of resource data matching that type.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to findAll, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing records for type. Existing records for the type will not be removed.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

adapter.findAll is called whenever store.findAll is asked to reload or backgroundReload. The records in the response are merged with the contents of the store. Existing records for the type will not be removed.

See also shouldReloadAll and shouldBackgroundReloadAll

store
Store

The store service that initiated the request being normalized

snapshot
Snapshot

A Snapshot containing the parent record's current data

relatedLink
String

The link at which the associated resource might be found

relationship
RelationshipSchema
returns
Promise

a promise resolving with resource data to feed to the associated serializer

adapter.findBelongsTo takes a request to fetch a related resource located at a relatedLink and should return a Promise which fulfills with data for a single resource.

⚠️ This method is only called if the store previously received relationship information for a resource containing a related link.

If the cache does not have a link for the relationship then findRecord will be used if a type and id for the related resource is known.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to findBelongsTo, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing data.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

store
Store

The store service that initiated the request being normalized

schema
ModelSchema

An object with methods for accessing information about the type, attributes and relationships of the primary type associated with the request.

ids
Array<string>

An array of the ids of the resources to fetch

snapshots
Array<Snapshot>

An array of snapshots of the available data for the resources to fetch

returns
Promise

a promise resolving with resource data to feed to the associated serializer

⚠️ This Method is only called if coalesceFindRequests is true. The array passed to it is determined by the adapter's groupRecordsForFindMany method, and will be called once per group returned.

adapter.findMany takes a request to fetch a collection of resources and should return a Promise which fulfills with data for that collection.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to findMany, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing data.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

See also groupRecordsForFindMany and coalesceFindRequests

store
Store

The store service that initiated the request being normalized

schema
ModelSchema

An object with methods for accessing information about the type, attributes and relationships of the primary type associated with the request.

id
String
snapshot
Snapshot
returns
Promise

a promise resolving with resource data to feed to the associated serializer

adapter.findRecord takes a request for a resource of a given type and id combination and should return a Promise which fulfills with data for a single resource matching that type and id.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to findRecord, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing data for the record.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

adapter.findRecord is called whenever the store needs to load, reload, or backgroundReload the resource data for a given type and id.

store
Store

The store service that initiated the request being normalized

snapshot
Snapshot

A Snapshot containing the parent record's current data

relatedLink
String

The link at which the associated resource collection might be found

relationship
RelationshipSchema
returns
Promise

a promise resolving with resource data to feed to the associated serializer

adapter.findHasMany takes a request to fetch a related resource collection located at a relatedLink and should return a Promise which fulfills with data for that collection.

⚠️ This method is only called if the store previously received relationship information for a resource containing a related link.

If the cache does not have a link for the relationship but the type and id of related resources are known then findRecord will be used for each individual related resource.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to findHasMany, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing data.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

store
Store

The store service that initiated the request being normalized

type
String

The type (or modelName) of record being created

properties

the properties passed as the second arg to store.createRecord

returns
String

a string ID that should be unique (no other models of type in the cache should have this id)

This method provides the ability to generate an ID to assign to a new record whenever store.createRecord is called if no id was provided.

Alternatively you can pass an id into the call to store.createRecord directly.

let id = generateNewId(type);
let newRecord = store.createRecord(type, { id });
store
Store

The store service that initiated the request being normalized

snapshots
Array<Snapshot>

An array of snapshots

returns
Array<Array<Snapshot>>

An array of Snapshot arrays

⚠️ This Method is only called if coalesceFindRequests is true.

This method allows for you to split pending requests for records into multiple findMany requests. It receives an array of snapshots where each snapshot represents a unique record requested via store.findRecord during the most recent runloop that was not found in the cache or needs to be reloaded. It should return an array of groups.

A group is an array of snapshots meant to be fetched together by a single findMany request.

By default if this method is not implemented EmberData will call findMany once with all requested records as a single group when coalesceFindRequests is true.

See also findMany and coalesceFindRequests

store
Store

The store service that initiated the request being normalized

schema
ModelSchema

An object with methods for accessing information about the type, attributes and relationships of the primary type associated with the request.

query
Object
recordArray
Collection
options
Object
returns
Promise

a promise resolving with resource data to feed to the associated serializer

adapter.query takes a request for resources of a given type and should return a Promise which fulfills with a collection of resource data matching that type.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to query, which should return a JSON:API document.

As with findAll, the final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing records for type.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

adapter.query is called whenever store.query is called or a previous query result is asked to reload.

Existing records for the type will not be removed. The key difference is in the result returned by the store. For findAll the result is all known records of the type, while for query it will only be the records returned from adapter.query.

store
Store

The store service that initiated the request being normalized

schema
ModelSchema

An object with methods for accessing information about the type, attributes and relationships of the primary type associated with the request.

query
options
returns
Promise

a promise resolving with resource data to feed to the associated serializer

adapter.queryRecord takes a request for resource of a given type and should return a Promise which fulfills with data for a single resource matching that type.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to queryRecord, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing data for the returned record.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

store
Store

The store service that initiated the request being normalized

snapshotArray
SnapshotRecordArray
returns
Boolean

true if the a new request for all records of the type in SnapshotRecordArray should be made in the background, false otherwise

When store.findAll(<type>) is called and a reload is not initiated, the adapter is presented the opportunity to trigger a new non-blocking (background) request for records of that type

Users may explicitly declare that this background request should/should not occur by passing backgroundReload: true or backgroundReload: false as an option to the request respectively.

store.findAll('user', { backgroundReload: false })

The default behavior if this method is not implemented and the option is not specified is to perform a reload, the same as a return of true.

store
Store

The store service that initiated the request being normalized

snapshot
Snapshot

A Snapshot containing the record's current data

returns
Boolean

true if the record should be reloaded in the background, false otherwise

When a record is already available in the store and is requested again via store.findRecord, and the record does not need to be reloaded prior to return, this method provides the ability to specify whether a refresh of the data for the reload should be scheduled to occur in the background.

Users may explicitly declare a record should/should not be background reloaded by passing backgroundReload: true or backgroundReload: false as an option to the request respectively.

store.findRecord('user', '1', { backgroundReload: false })

If the backgroundReload option is not present, this method will be called to determine whether a backgroundReload should be performed.

The default behavior if this method is not implemented and the option was not specified is to background reload, the same as a return of true.

store
Store

The store service that initiated the request being normalized

snapshotArray
SnapshotRecordArray
returns
Boolean

true if the a new request for all records of the type in SnapshotRecordArray should be made immediately, false otherwise

When store.findAll(<type>) is called without a reload option, the adapter is presented the opportunity to trigger a new request for records of that type.

If reload is specified as an option in the request (true or false) this method will not be called.

store.findAll('user', { reload: false })

The default behavior if this method is not implemented and the option is not specified is to not reload, the same as a return of false.

Note: the Promise returned by store.findAll resolves to the same RecordArray instance returned by store.peekAll for that type, and will include all records in the store for the given type, including any previously existing records not returned by the reload request.

store
Store

The store service that initiated the request being normalized

snapshot
Snapshot

A Snapshot containing the record's current data

returns
Boolean

true if the record should be reloaded immediately, false otherwise

When a record is already available in the store and is requested again via store.findRecord, and reload is not specified as an option in the request, this method is called to determine whether the record should be reloaded prior to returning the result.

If reload is specified as an option in the request (true or false) this method will not be called.

store.findRecord('user', '1', { reload: false })

The default behavior if this method is not implemented and the option is not specified is to not reload, the same as a return of false.

See also the documentation for shouldBackgroundReloadRecord which defaults to true.

store
Store

The store service that initiated the request being normalized

schema
ModelSchema

An object with methods for accessing information about the type, attributes and relationships of the primary type associated with the request.

snapshot
Snapshot

adapter.updateRecord takes a request to update a resource of a given type and should return a Promise which fulfills with the updated data for the resource.

The response will be fed to the associated serializer's normalizeResponse method with the requestType set to updateRecord, which should return a JSON:API document.

The final result after normalization to JSON:API will be added to store via store.push where it will merge with any existing data for the record.

⚠️ If the adapter's response resolves to a false-y value, the associated serializer.normalizeResponse call will NOT be made. In this scenario you may need to do at least a minimum amount of response processing within the adapter.

If the adapter rejects or throws an error the record will enter an error state and the attributes that had attempted to be saved will still be considered dirty.

InvalidErrors

When rejecting a createRecord request due to validation issues during save (typically a 422 status code), you may throw an InvalidError.

Throwing an InvalidError makes per-attribute errors available for records to use in the UI as needed. Records can also use this information to mark themselves as being in an invalid state. For more reading see the RecordData Errors RFC

let error = new Error(errorMessage);

// these two properties combined
// alert EmberData to this error being for
// invalid properties on the record during
// the request
error.isAdapterError = true;
error.code = 'InvalidError';

// A JSON:API formatted array of errors
// See https://jsonapi.org/format/#errors
error.errors = [];

throw error;