Class DS.JSONSerializer

Extends: DS.Serializer
Defined in: addon/serializers/json.js:17
Module: ember-data

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.

By default, Ember Data uses and recommends the JSONAPISerializer.

JSONSerializer is useful for simpler or legacy backends that may not support the http://jsonapi.org/ spec.

For example, given the following User model and JSON payload:

app/models/user.js
import DS from 'ember-data';

export default DS.Model.extend({
  friends: DS.hasMany('user'),
  house: DS.belongsTo('location'),

  name: DS.attr('string')
});
{
  id: 1,
  name: 'Sebastian',
  friends: [3, 4],
  links: {
    house: '/houses/lefkada'
  }
}

JSONSerializer will normalize the JSON payload to the JSON API format that the Ember Data store expects.

You can customize how JSONSerializer processes its payload by passing options in the attrs hash or by subclassing the JSONSerializer and overriding hooks:

  • To customize how a single record is normalized, use the normalize hook.
  • To customize how JSONSerializer normalizes the whole server response, use the normalizeResponse hook.
  • To customize how JSONSerializer normalizes a specific response from the server, use one of the many specific normalizeResponse hooks.
  • To customize how JSONSerializer normalizes your id, attributes or relationships, use the extractId, extractAttributes and extractRelationships hooks.

The JSONSerializer normalization process follows these steps:

  • normalizeResponse - entry method to the serializer.
  • normalizeCreateRecordResponse - a normalizeResponse for a specific operation is called.
  • normalizeSingleResponse|normalizeArrayResponse - for methods like createRecord we expect a single record back, while for methods like findAll we expect multiple records back.
  • normalize - normalizeArray iterates and calls normalize for each of its records while normalizeSingle calls it once. This is the method you most likely want to subclass.
  • extractId | extractAttributes | extractRelationships - normalize delegates to these methods to turn the record payload into the JSON API format.

Show:

attrs

Module: ember-data

Defined in addon/serializers/json.js:109

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
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
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
import DS from 'ember-data';

export default DS.JSONSerializer.extend({
  attrs: {
    admin: { serialize: false },
    occupation: { key: 'career' }
  }
});

When serialized:

{
  "firstName": "Harry",
  "lastName": "Houdini",
  "career": "magician"
}

Note that the admin is now not included in the payload.

primaryKey

Module: ember-data

Defined in addon/serializers/json.js:85

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
import DS from 'ember-data';

export default DS.JSONSerializer.extend({
  primaryKey: '_id'
});

store public

Module: ember-data

Inherited from DS.Serializer addon/serializer.js:29

The store property is the application's store that contains all records. It can be used to look up serializers for other model types that may be nested inside the payload response.

Example:

Serializer.extend({
  extractRelationship(relationshipModelName, relationshipHash) {
    var modelClass = this.store.modelFor(relationshipModelName);
    var relationshipSerializer = this.store.serializerFor(relationshipModelName);
    return relationshipSerializer.normalize(modelClass, relationshipHash);
  }
});