DS.JSONAPISerializer Class addon/serializers/json-api.js:14
Ember Data 2.0 Serializer:
In Ember Data a Serializer is used to serialize and deserialize records when they are transferred in and out of an external source. This process involves normalizing property names, transforming attribute values and serializing relationships.
JSONAPISerializer
supports the http://jsonapi.org/ spec and is the
serializer recommended by Ember Data.
This serializer normalizes a JSON API payload that looks like:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
// models/player.js import DS from "ember-data"; export default DS.Model.extend({ name: DS.attr(), skill: DS.attr(), gamesPlayed: DS.attr(), club: DS.belongsTo('club') }); // models/club.js import DS from "ember-data"; export default DS.Model.extend({ name: DS.attr(), location: DS.attr(), players: DS.hasMany('player') }); |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 |
{ "data": [ { "attributes": { "name": "Benfica", "location": "Portugal" }, "id": "1", "relationships": { "players": { "data": [ { "id": "3", "type": "players" } ] } }, "type": "clubs" } ], "included": [ { "attributes": { "name": "Eusebio Silva Ferreira", "skill": "Rocket shot", "games-played": 431 }, "id": "3", "relationships": { "club": { "data": { "id": "1", "type": "clubs" } } }, "type": "players" } ] } |
to the format that the Ember Data store expects.
Methods
- _canSerialize
- _extractType
- _getMappedKey
- _mustSerialize
- _normalizeDocumentHelper
- _normalizeRelationshipDataHelper
- _normalizeResourceHelper
- _normalizeResponse
- _shouldSerializeHasMany
- applyTransforms
- extractAttributes
- extractErrors
- extractId
- extractMeta
- extractPolymorphicRelationship
- extractRelationship
- extractRelationships
- keyForAttribute
- keyForLink
- keyForRelationship
- modelNameFromPayloadKey
- normalize
- normalizeArrayResponse
- normalizeAttributes
- normalizeCreateRecordResponse
- normalizeDeleteRecordResponse
- normalizeFindAllResponse
- normalizeFindBelongsToResponse
- normalizeFindHasManyResponse
- normalizeFindManyResponse
- normalizeFindRecordResponse
- normalizeQueryRecordResponse
- normalizeQueryResponse
- normalizeRelationships
- normalizeResponse
- normalizeSaveResponse
- normalizeSingleResponse
- normalizeUpdateRecordResponse
- normalizeUsingDeclaredMapping
- payloadKeyFromModelName
- pushPayload
- serialize
- serializeAttribute
- serializeBelongsTo
- serializeHasMany
- serializeIntoHash
- serializePolymorphicType
- transformFor
Properties
_canSerialize
(key)
Boolean
private
Check attrs.key.serialize property to inform if the key
can be serialized
Parameters:
- key String
Returns:
- Boolean
- true if the key can be serialized
_extractType
(modelClass, resourceHash)
String
private
Parameters:
- modelClass DS.Model
- resourceHash Object
Returns:
- String
_getMappedKey
(key)
String
private
Looks up the property key that was set by the custom attr
mapping
passed to the serializer.
Parameters:
- key String
Returns:
- String
- key
_mustSerialize
(key)
Boolean
private
When attrs.key.serialize is set to true then it takes priority over the other checks and the related attribute/relationship will be serialized
Parameters:
- key String
Returns:
- Boolean
- true if the key must be serialized
_normalizeDocumentHelper
(documentHash)
Object
private
Parameters:
- documentHash Object
Returns:
- Object
_normalizeRelationshipDataHelper
(relationshipDataHash)
Object
private
Parameters:
- relationshipDataHash Object
Returns:
- Object
_normalizeResourceHelper
(resourceHash)
Object
private
Parameters:
- resourceHash Object
Returns:
- Object
_normalizeResponse
(store, primaryModelClass, payload, id, requestType, isSingle)
Object
private
Parameters:
Returns:
- Object
- JSON-API Document
_shouldSerializeHasMany
(snapshot, key, relationshipType)
Boolean
private
Check if the given hasMany relationship should be serialized
Parameters:
- snapshot DS.Snapshot
- key String
- relationshipType String
Returns:
- Boolean
- true if the hasMany relationship should be serialized
applyTransforms
(typeClass, data)
Object
private
Given a subclass of DS.Model
and a JSON object this method will
iterate through each attribute of the DS.Model
and invoke the
DS.Transform#deserialize
method on the matching property of the
JSON object. This method is typically called after the
serializer's normalize
method.
Parameters:
- typeClass DS.Model
- data Object
- The data to transform
Returns:
- Object
- data The transformed data object
extractAttributes
(modelClass, resourceHash)
Object
Parameters:
- modelClass DS.Model
- resourceHash Object
Returns:
- Object
extractErrors
(store, typeClass, payload, id)
Object
extractErrors
is used to extract model errors when a call
to DS.Model#save
fails with an InvalidError
. By default
Ember Data expects error information to be located on the errors
property of the payload object.
This serializer expects this errors
object to be an Array similar
to the following, compliant with the JSON-API specification:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
{ "errors": [ { "detail": "This username is already taken!", "source": { "pointer": "data/attributes/username" } }, { "detail": "Doesn't look like a valid email.", "source": { "pointer": "data/attributes/email" } } ] } |
The key detail
provides a textual description of the problem.
Alternatively, the key title
can be used for the same purpose.
The nested keys source.pointer
detail which specific element
of the request data was invalid.
Note that JSON-API also allows for object-level errors to be placed
in an object with pointer data
, signifying that the problem
cannot be traced to a specific attribute:
1 2 3 4 5 6 7 8 9 10 |
{ "errors": [ { "detail": "Some generic non property error message", "source": { "pointer": "data" } } ] } |
When turn into a DS.Errors
object, you can read these errors
through the property base
:
Example of alternative implementation, overriding the default behavior to deal with a different format of errors:
app/serializers/post.js | |
1 2 3 4 5 6 7 8 9 10 11 |
import DS from 'ember-data'; export default DS.JSONSerializer.extend({ extractErrors: function(store, typeClass, payload, id) { if (payload && typeof payload === 'object' && payload._problems) { payload = payload._problems; this.normalizeErrors(typeClass, payload); } return payload; } }); |
Returns:
- Object
- json The deserialized errors
extractId
(modelClass, resourceHash)
String
Returns the resource's ID.
Parameters:
- modelClass Object
- resourceHash Object
Returns:
- String
extractMeta
(store, modelClass, payload)
extractMeta
is used to deserialize any meta information in the
adapter payload. By default Ember Data expects meta information to
be located on the meta
property of the payload object.
Example
app/serializers/post.js | |
1 2 3 4 5 6 7 8 9 10 11 |
import DS from 'ember-data'; export default DS.JSONSerializer.extend({ extractMeta: function(store, typeClass, payload) { if (payload && payload.hasOwnProperty('_pagination')) { let meta = payload._pagination; delete payload._pagination; return meta; } } }); |
extractPolymorphicRelationship
(relationshipModelName, relationshipHash, relationshipOptions)
Object
Returns a polymorphic relationship formatted as a JSON-API "relationship object".
http://jsonapi.org/format/#document-resource-object-relationships
relationshipOptions
is a hash which contains more information about the
polymorphic relationship which should be extracted:
- resourceHash
complete hash of the resource the relationship should be
extracted from
- relationshipKey
key under which the value for the relationship is
extracted from the resourceHash
- relationshipMeta
meta information about the relationship
Parameters:
- relationshipModelName Object
- relationshipHash Object
- relationshipOptions Object
Returns:
- Object
extractRelationship
(relationshipHash)
Object
Parameters:
- relationshipHash Object
Returns:
- Object
extractRelationships
(modelClass, resourceHash)
Object
Parameters:
- modelClass Object
- resourceHash Object
Returns:
- Object
keyForAttribute
(key, method)
String
keyForAttribute
can be used to define rules for how to convert an
attribute name in your model to a key in your JSON.
By default JSONAPISerializer
follows the format used on the examples of
http://jsonapi.org/format and uses dashes as the word separator in the JSON
attribute keys.
This behaviour can be easily customized by extending this method.
Example
app/serializers/application.js | |
1 2 3 4 5 6 7 |
import DS from 'ember-data'; export default DS.JSONAPISerializer.extend({ keyForAttribute: function(attr, method) { return Ember.String.dasherize(attr).toUpperCase(); } }); |
Parameters:
- key String
- method String
Returns:
- String
- normalized key
keyForLink
(key, kind)
String
keyForLink
can be used to define a custom key when deserializing link
properties.
Parameters:
- key String
- kind String
- `belongsTo` or `hasMany`
Returns:
- String
- normalized key
keyForRelationship
(key, typeClass, method)
String
keyForRelationship
can be used to define a custom key when
serializing and deserializing relationship properties.
By default JSONAPISerializer
follows the format used on the examples of
http://jsonapi.org/format and uses dashes as word separators in
relationship properties.
This behaviour can be easily customized by extending this method.
Example
app/serializers/post.js | |
1 2 3 4 5 6 7 |
import DS from 'ember-data'; export default DS.JSONAPISerializer.extend({ keyForRelationship: function(key, relationship, method) { return Ember.String.underscore(key); } }); |
Parameters:
- key String
- typeClass String
- method String
Returns:
- String
- normalized key
modelNameFromPayloadKey
(key)
String
Parameters:
- key String
Returns:
- String
- the model's modelName
normalize
(modelClass, resourceHash)
Object
Parameters:
- modelClass DS.Model
- resourceHash Object
- the resource hash from the adapter
Returns:
- Object
- the normalized resource hash
normalizeArrayResponse
(store, primaryModelClass, payload, id, requestType)
Object
Parameters:
Returns:
- Object
- JSON-API Document
normalizeAttributes
private
normalizeCreateRecordResponse
(store, primaryModelClass, payload, id, requestType)
Object
Parameters:
Returns:
- Object
- JSON-API Document
normalizeDeleteRecordResponse
(store, primaryModelClass, payload, id, requestType)
Object
Parameters:
Returns:
- Object
- JSON-API Document
normalizeFindAllResponse
(store, primaryModelClass, payload, id, requestType)
Object
Parameters:
Returns:
- Object
- JSON-API Document
normalizeFindBelongsToResponse
(store, primaryModelClass, payload, id, requestType)
Object
Parameters:
Returns:
- Object
- JSON-API Document
normalizeFindHasManyResponse
(store, primaryModelClass, payload, id, requestType)
Object
Parameters:
Returns:
- Object
- JSON-API Document
normalizeFindManyResponse
(store, primaryModelClass, payload, id, requestType)
Object
Parameters:
Returns:
- Object
- JSON-API Document
normalizeFindRecordResponse
(store, primaryModelClass, payload, id, requestType)
Object
Parameters:
Returns:
- Object
- JSON-API Document
normalizeQueryRecordResponse
(store, primaryModelClass, payload, id, requestType)
Object
Parameters:
Returns:
- Object
- JSON-API Document
normalizeQueryResponse
(store, primaryModelClass, payload, id, requestType)
Object
Parameters:
Returns:
- Object
- JSON-API Document
normalizeRelationships
private
normalizeResponse
(store, primaryModelClass, payload, id, requestType)
Object
The normalizeResponse
method is used to normalize a payload from the
server to a JSON-API Document.
http://jsonapi.org/format/#document-structure
This method delegates to a more specific normalize method based on
the requestType
.
To override this method with a custom one, make sure to call
return this._super(store, primaryModelClass, payload, id, requestType)
with your
pre-processed data.
Here's an example of using normalizeResponse
manually:
1 2 3 4 5 6 7 8 |
socket.on('message', function(message) { var data = message.data; var modelClass = store.modelFor(data.modelName); var serializer = store.serializerFor(data.modelName); var normalized = serializer.normalizeSingleResponse(store, modelClass, data, data.id); store.push(normalized); }); |
Parameters:
Returns:
- Object
- JSON-API Document
normalizeSaveResponse
(store, primaryModelClass, payload, id, requestType)
Object
Parameters:
Returns:
- Object
- JSON-API Document
normalizeSingleResponse
(store, primaryModelClass, payload, id, requestType)
Object
Parameters:
Returns:
- Object
- JSON-API Document
normalizeUpdateRecordResponse
(store, primaryModelClass, payload, id, requestType)
Object
Parameters:
Returns:
- Object
- JSON-API Document
normalizeUsingDeclaredMapping
private
payloadKeyFromModelName
(modelName)
String
Parameters:
- modelName String
Returns:
- String
serialize
(snapshot, options)
Object
Parameters:
- snapshot DS.Snapshot
- options Object
Returns:
- Object
- json
serializeAttribute
(snapshot, json, key, attribute)
Parameters:
- snapshot DS.Snapshot
- json Object
- key String
- attribute Object
serializeBelongsTo
(snapshot, json, relationship)
Parameters:
- snapshot DS.Snapshot
- json Object
- relationship Object
serializeHasMany
(snapshot, json, relationship)
Parameters:
- snapshot DS.Snapshot
- json Object
- relationship Object
serializeIntoHash
(hash, typeClass, snapshot, options)
You can use this method to customize how a serialized record is added to the complete JSON hash to be sent to the server. By default the JSON Serializer does not namespace the payload and just sends the raw serialized JSON object. If your server expects namespaced keys, you should consider using the RESTSerializer. Otherwise you can override this method to customize how the record is added to the hash. The hash property should be modified by reference.
For example, your server may expect underscored root objects.
app/serializers/application.js | |
1 2 3 4 5 6 7 8 |
import DS from 'ember-data'; export default DS.RESTSerializer.extend({ serializeIntoHash: function(data, type, snapshot, options) { var root = Ember.String.decamelize(type.modelName); data[root] = this.serialize(snapshot, options); } }); |
Parameters:
- hash Object
- typeClass DS.Model
- snapshot DS.Snapshot
- options Object
serializePolymorphicType
(snapshot, json, relationship)
You can use this method to customize how polymorphic objects are
serialized. Objects are considered to be polymorphic if
{ polymorphic: true }
is pass as the second argument to the
DS.belongsTo
function.
Example
app/serializers/comment.js | |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
import DS from 'ember-data'; export default DS.JSONSerializer.extend({ serializePolymorphicType: function(snapshot, json, relationship) { var key = relationship.key, belongsTo = snapshot.belongsTo(key); key = this.keyForAttribute ? this.keyForAttribute(key, "serialize") : key; if (Ember.isNone(belongsTo)) { json[key + "_type"] = null; } else { json[key + "_type"] = belongsTo.modelName; } } }); |
Parameters:
- snapshot DS.Snapshot
- json Object
- relationship Object
transformFor
(attributeType, skipAssertion)
DS.Transform
private
Parameters:
- attributeType String
- skipAssertion Boolean
Returns:
- DS.Transform
- transform
attrs
{Object}
The attrs
object can be used to declare a simple mapping between
property names on DS.Model
records and payload keys in the
serialized JSON object representing the record. An object with the
property key
can also be used to designate the attribute's key on
the response payload.
Example
app/models/person.js | |
1 2 3 4 5 6 7 8 |
import DS from 'ember-data'; export default DS.Model.extend({ firstName: DS.attr('string'), lastName: DS.attr('string'), occupation: DS.attr('string'), admin: DS.attr('boolean') }); |
app/serializers/person.js | |
1 2 3 4 5 6 7 8 |
import DS from 'ember-data'; export default DS.JSONSerializer.extend({ attrs: { admin: 'is_admin', occupation: { key: 'career' } } }); |
You can also remove attributes by setting the serialize
key to
false
in your mapping object.
Example
app/serializers/person.js | |
1 2 3 4 5 6 7 8 |
import DS from 'ember-data'; export default DS.JSONSerializer.extend({ attrs: { admin: { serialize: false }, occupation: { key: 'career' } } }); |
When serialized:
1 2 3 4 5 |
{ "firstName": "Harry", "lastName": "Houdini", "career": "magician" } |
Note that the admin
is now not included in the payload.
primaryKey
{String}
The primaryKey
is used when serializing and deserializing
data. Ember Data always uses the id
property to store the id of
the record. The external source may not always follow this
convention. In these cases it is useful to override the
primaryKey
property to match the primaryKey
of your external
store.
Example
app/serializers/application.js | |
1 2 3 4 5 |
import DS from 'ember-data'; export default DS.JSONSerializer.extend({ primaryKey: '_id' }); |
Default: 'id'
store
{DS.Store}
public
The store
property is the application's store
that contains all records.
It's injected as a service.
It can be used to push records from a non flat data structure server
response.