Class JSONAPISerializer

public

Defined in: ../serializer/src/json-api.js:12

Since: v1.13.0

⚠️ 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

In EmberData 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:

app/models/player.js

 import Model, { attr, belongsTo } from '@ember-data/model';

 export default class Player extends Model {
   @attr('string') name;
   @attr('string') skill;
   @attr('number') gamesPlayed;
   @belongsTo('club') club;
 }

app/models/club.js

 import Model, { attr, hasMany } from '@ember-data/model';

 export default class Club extends Model {
   @attr('string') name;
   @attr('string') location;
   @hasMany('player') players;
 }

   {
     "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.

### Customizing meta

Since a JSON API Document can have meta defined in multiple locations you can use the specific serializer hooks if you need to customize the meta.

One scenario would be to camelCase the meta keys of your payload. The example below shows how this could be done using normalizeArrayResponse and extractRelationship.

app/serializers/application.js

 import JSONAPISerializer from '@ember-data/serializer/json-api';

 export default class ApplicationSerializer extends JSONAPISerializer {
   normalizeArrayResponse(store, primaryModelClass, payload, id, requestType) {
     let normalizedDocument = super.normalizeArrayResponse(...arguments);

     // Customize document meta
     normalizedDocument.meta = camelCaseKeys(normalizedDocument.meta);

     return normalizedDocument;
   }

   extractRelationship(relationshipHash) {
     let normalizedRelationship = super.extractRelationship(...arguments);

     // Customize relationship meta
     normalizedRelationship.meta = camelCaseKeys(normalizedRelationship.meta);

     return normalizedRelationship;
   }
 }

@mainName @ember-data/serializer/json-api @tag main

Show: Inherited Protected Private Deprecated

attrs public

Module: @ember-data/serializer/json-api

Inherited from JSONSerializer ../packages/serializer/src/json.js:120

The attrs object can be used to declare a simple mapping between property names on 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 Model, { attr } from '@ember-data/model';

export default class PersonModel extends Model {
  @attr('string') firstName;
  @attr('string') lastName;
  @attr('string') occupation;
  @attr('boolean') admin;
}

app/serializers/person.js

import JSONSerializer from '@ember-data/serializer/json';

export default class PersonSerializer extends JSONSerializer {
  attrs = {
    admin: 'is_admin',
    occupation: { key: 'career' }
  }
}

You can also remove attributes and relationships by setting the serialize key to false in your mapping object.

Example

app/serializers/person.js

import JSONSerializer from '@ember-data/serializer/json';

export default class PostSerializer extends JSONSerializer {
  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.

Setting serialize to true enforces serialization for hasMany relationships even if it's neither a many-to-many nor many-to-none relationship.

primaryKey public

Module: @ember-data/serializer/json-api

Inherited from JSONSerializer ../packages/serializer/src/json.js:95

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 JSONSerializer from '@ember-data/serializer/json';

export default class ApplicationSerializer extends JSONSerializer {
  primaryKey = '_id'
}

store public

Module: @ember-data/serializer/json-api

Inherited from Serializer ../packages/serializer/src/index.ts:142

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) {
    let modelClass = this.store.modelFor(relationshipModelName);
    let relationshipSerializer = this.store.serializerFor(relationshipModelName);
    return relationshipSerializer.normalize(modelClass, relationshipHash);
  }
});