Documentation / @ember-data/serializer / json-api / default

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:124

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

Since

1.13.0 JSONAPISerializer

Constructors

Constructor

new default(owner?): default;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:168

Parameters

owner?

any

Returns

default

Properties

store

store: default;

Defined in: warp-drive-packages/legacy/declarations/serializer.d.ts:134

---

mergedProperties

readonly static mergedProperties: any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:126

---

primaryKey

readonly static primaryKey: string;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:125

Methods

normalize()

normalize(_typeClass, hash): 
  | SingleResourceDocument
  | EmptyResourceDocument;

Defined in: warp-drive-packages/legacy/declarations/serializer.d.ts:256

The normalize method is used to convert a payload received from your external data source into the normalized form store.push() expects. You should override this method, munge the hash and return the normalized payload.

Example:

Serializer.extend({
  normalize(modelClass, resourceHash) {
    let data = {
      id:            resourceHash.id,
      type:          modelClass.modelName,
      attributes:    resourceHash
    };
    return { data: data };
  }
})

Parameters

_typeClass

ModelSchema

hash

Record<string, unknown>

Returns

| SingleResourceDocument | EmptyResourceDocument

---

_canSerialize()

readonly static _canSerialize(key): boolean;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:153

Parameters

key

string

Returns

boolean

---

_getMappedKey()

readonly static _getMappedKey(key, modelClass): string;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:152

Parameters

key

string

modelClass

any

Returns

string

---

_mustSerialize()

readonly static _mustSerialize(key): boolean;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:154

Parameters

key

string

Returns

boolean

---

_normalizeResponse()

static _normalizeResponse(
   store, 
   primaryModelClass, 
   payload, 
   id, 
   requestType, 
   isSingle): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:142

Parameters

store

Store

primaryModelClass

Model

payload

any

id

string | number

requestType

string

isSingle

boolean

Returns

any

---

applyTransforms()

readonly static applyTransforms(typeClass, data): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:127

Parameters

typeClass

Model

data

any

Returns

any

---

extractAttributes()

Call Signature

static extractAttributes(modelClass, resourceHash): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:145

Parameters

modelClass

any

resourceHash

any

Returns

any

Call Signature

static extractAttributes(modelClass, resourceHash): object;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:207

Parameters

modelClass

any

resourceHash

any

Returns

object

---

extractErrors()

readonly static extractErrors(
   store, 
   typeClass, 
   payload, 
   id): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:163

Parameters

store

Store

typeClass

Model

payload

any

id

string | number

Returns

any

---

extractId()

readonly static extractId(modelClass, resourceHash): string;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:144

Parameters

modelClass

any

resourceHash

any

Returns

string

---

extractMeta()

readonly static extractMeta(
   store, 
   modelClass, 
   payload): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:162

Parameters

store

Store

modelClass

Model

payload

any

Returns

any

---

extractPolymorphicRelationship()

readonly static extractPolymorphicRelationship(
   relationshipModelName, 
   relationshipHash, 
   relationshipOptions): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:147

Parameters

relationshipModelName

any

relationshipHash

any

relationshipOptions

any

Returns

any

---

extractRelationship()

Call Signature

static extractRelationship(relationshipModelName, relationshipHash): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:146

Parameters

relationshipModelName

any

relationshipHash

any

Returns

any

Call Signature

static extractRelationship(relationshipHash): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:217

Returns a relationship formatted as a JSON-API "relationship object".

http://jsonapi.org/format/#document-resource-object-relationships

Parameters

relationshipHash

any

Returns

any

---

extractRelationships()

static extractRelationships(modelClass, resourceHash): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:148

Parameters

modelClass

any

resourceHash

any

Returns

any

---

keyForAttribute()

static keyForAttribute(key, method): string;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:164

Parameters

key

string

method

string

Returns

string

---

keyForLink()

readonly static keyForLink(key, kind): string;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:166

Parameters

key

string

kind

string

Returns

string

---

keyForRelationship()

static keyForRelationship(
   key, 
   typeClass, 
   method): string;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:165

Parameters

key

string

typeClass

string

method

string

Returns

string

---

modelNameFromPayloadKey()

static modelNameFromPayloadKey(key): string;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:149

Parameters

key

string

Returns

string

---

normalize()

Call Signature

static normalize(modelClass, resourceHash): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:143

Parameters

modelClass

any

resourceHash

any

Returns

any

Call Signature

static normalize(modelClass, resourceHash): object;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:259

Parameters

modelClass

any

resourceHash

any

Returns

object

data

data: object;

data.attributes

data.attributes: object;

data.id

data.id: any;

data.relationships

data.relationships: any;

data.type

data.type: string;

---

normalizeArrayResponse()

readonly static normalizeArrayResponse(
   store, 
   primaryModelClass, 
   payload, 
   id, 
   requestType): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:141

Parameters

store

Store

primaryModelClass

Model

payload

any

id

string | number

requestType

string

Returns

any

---

normalizeCreateRecordResponse()

readonly static normalizeCreateRecordResponse(
   store, 
   primaryModelClass, 
   payload, 
   id, 
   requestType, ...
   args): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:136

Parameters

store

Store

primaryModelClass

Model

payload

any

id

string | number

requestType

string

args

...any[]

Returns

any

---

normalizeDeleteRecordResponse()

readonly static normalizeDeleteRecordResponse(
   store, 
   primaryModelClass, 
   payload, 
   id, 
   requestType, ...
   args): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:137

Parameters

store

Store

primaryModelClass

Model

payload

any

id

string | number

requestType

string

args

...any[]

Returns

any

---

normalizeFindAllResponse()

readonly static normalizeFindAllResponse(
   store, 
   primaryModelClass, 
   payload, 
   id, 
   requestType, ...
   args): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:131

Parameters

store

Store

primaryModelClass

Model

payload

any

id

string | number

requestType

string

args

...any[]

Returns

any

---

normalizeFindBelongsToResponse()

readonly static normalizeFindBelongsToResponse(
   store, 
   primaryModelClass, 
   payload, 
   id, 
   requestType, ...
   args): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:132

Parameters

store

Store

primaryModelClass

Model

payload

any

id

string | number

requestType

string

args

...any[]

Returns

any

---

normalizeFindHasManyResponse()

readonly static normalizeFindHasManyResponse(
   store, 
   primaryModelClass, 
   payload, 
   id, 
   requestType, ...
   args): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:133

Parameters

store

Store

primaryModelClass

Model

payload

any

id

string | number

requestType

string

args

...any[]

Returns

any

---

normalizeFindManyResponse()

readonly static normalizeFindManyResponse(
   store, 
   primaryModelClass, 
   payload, 
   id, 
   requestType, ...
   args): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:134

Parameters

store

Store

primaryModelClass

Model

payload

any

id

string | number

requestType

string

args

...any[]

Returns

any

---

normalizeFindRecordResponse()

readonly static normalizeFindRecordResponse(
   store, 
   primaryModelClass, 
   payload, 
   id, 
   requestType, ...
   args): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:129

Parameters

store

Store

primaryModelClass

Model

payload

any

id

string | number

requestType

string

args

...any[]

Returns

any

---

normalizeQueryRecordResponse()

Call Signature

static normalizeQueryRecordResponse(
   store, 
   primaryModelClass, 
   payload, 
   id, 
   requestType, ...
   args): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:130

Parameters

store

Store

primaryModelClass

Model

payload

any

id

string | number

requestType

string

args

...any[]

Returns

any

Call Signature

static normalizeQueryRecordResponse(...args): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:206

Parameters

args

...any[]

Returns

any

---

normalizeQueryResponse()

readonly static normalizeQueryResponse(
   store, 
   primaryModelClass, 
   payload, 
   id, 
   requestType, ...
   args): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:135

Parameters

store

Store

primaryModelClass

Model

payload

any

id

string | number

requestType

string

args

...any[]

Returns

any

---

normalizeRelationships()

readonly static normalizeRelationships(typeClass, hash): void;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:150

Parameters

typeClass

any

hash

any

Returns

void

---

normalizeResponse()

readonly static normalizeResponse(
   store, 
   primaryModelClass, 
   payload, 
   id, 
   requestType, ...
   args): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:128

Parameters

store

Store

primaryModelClass

Model

payload

any

id

string | number

requestType

string

args

...any[]

Returns

any

---

normalizeSaveResponse()

readonly static normalizeSaveResponse(
   store, 
   primaryModelClass, 
   payload, 
   id, 
   requestType, ...
   args): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:139

Parameters

store

Store

primaryModelClass

Model

payload

any

id

string | number

requestType

string

args

...any[]

Returns

any

---

normalizeSingleResponse()

readonly static normalizeSingleResponse(
   store, 
   primaryModelClass, 
   payload, 
   id, 
   requestType): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:140

Parameters

store

Store

primaryModelClass

Model

payload

any

id

string | number

requestType

string

Returns

any

---

normalizeUpdateRecordResponse()

readonly static normalizeUpdateRecordResponse(
   store, 
   primaryModelClass, 
   payload, 
   id, 
   requestType, ...
   args): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:138

Parameters

store

Store

primaryModelClass

Model

payload

any

id

string | number

requestType

string

args

...any[]

Returns

any

---

normalizeUsingDeclaredMapping()

readonly static normalizeUsingDeclaredMapping(modelClass, hash): void;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:151

Parameters

modelClass

any

hash

any

Returns

void

---

payloadKeyFromModelName()

static payloadKeyFromModelName(modelName): string;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:258

Converts the model name to a pluralized version of the model name.

For example post would be converted to posts and student-assesment would be converted to student-assesments.

Parameters

modelName

string

Returns

string

---

pushPayload()

static pushPayload(store, payload): void;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:194

Normalize some data and push it into the store.

Parameters

store

Store

payload

any

Returns

void

---

serialize()

Call Signature

static serialize(snapshot, options): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:156

Parameters

snapshot

Snapshot

options

any

Returns

any

Call Signature

static serialize(
   snapshot, 
   options, ...
   args): any;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:491

Called when a record is saved in order to convert the record into JSON.

For example, consider this model:

app/models/comment.js

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

export default class CommentModel extends Model {
  @attr title;
  @attr body;

  @belongsTo('user', { async: false, inverse: null })
  author;
}

The default serialization would create a JSON-API resource object like:

{
  "data": {
    "type": "comments",
    "attributes": {
      "title": "Rails is unagi",
      "body": "Rails? Omakase? O_O",
    },
    "relationships": {
      "author": {
        "data": {
          "id": "12",
          "type": "users"
        }
      }
    }
  }
}

By default, attributes are passed through as-is, unless you specified an attribute type (attr('date')). If you specify a transform, the JavaScript value will be serialized when inserted into the attributes hash.

Belongs-to relationships are converted into JSON-API resource identifier objects.

IDs

serialize takes an options hash with a single option: includeId. If this option is true, serialize will, by default include the ID in the JSON object it builds.

The JSONAPIAdapter passes in includeId: true when serializing a record for createRecord or updateRecord.

Customization

Your server may expect data in a different format than the built-in serialization format.

In that case, you can implement serialize yourself and return data formatted to match your API's expectations, or override the invoked adapter method and do the serialization in the adapter directly by using the provided snapshot.

If your API's format differs greatly from the JSON:API spec, you should consider authoring your own adapter and serializer instead of extending this class.

app/serializers/post.js

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

export default class PostSerializer extends JSONAPISerializer {
  serialize(snapshot, options) {
    let json = {
      POST_TTL: snapshot.attr('title'),
      POST_BDY: snapshot.attr('body'),
      POST_CMS: snapshot.hasMany('comments', { ids: true })
    };

    if (options.includeId) {
      json.POST_ID_ = snapshot.id;
    }

    return json;
  }
}

Customizing an App-Wide Serializer

If you want to define a serializer for your entire application, you'll probably want to use eachAttribute and eachRelationship on the record.

app/serializers/application.js

import JSONAPISerializer from '@ember-data/serializer/json-api';
import { underscore, singularize } from '<app-name>/utils/string-utils';

export default class ApplicationSerializer extends JSONAPISerializer {
  serialize(snapshot, options) {
    let json = {};

    snapshot.eachAttribute((name) => {
      json[serverAttributeName(name)] = snapshot.attr(name);
    });

    snapshot.eachRelationship((name, relationship) => {
      if (relationship.kind === 'hasMany') {
        json[serverHasManyName(name)] = snapshot.hasMany(name, { ids: true });
      }
    });

    if (options.includeId) {
      json.ID_ = snapshot.id;
    }

    return json;
  }
}

function serverAttributeName(attribute) {
  return underscore(attribute).toUpperCase();
}

function serverHasManyName(name) {
  return serverAttributeName(singularize(name)) + '_IDS';
}

This serializer will generate JSON that looks like this:

{
  "TITLE": "Rails is omakase",
  "BODY": "Yep. Omakase.",
  "COMMENT_IDS": [ "1", "2", "3" ]
}

Tweaking the Default Formatting

If you just want to do some small tweaks on the default JSON:API formatted response, you can call super.serialize first and make the tweaks on the returned object.

app/serializers/post.js

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

export default class PostSerializer extends JSONAPISerializer {
  serialize(snapshot, options) {
    let json = super.serialize(...arguments);

    json.data.attributes.subject = json.data.attributes.title;
    delete json.data.attributes.title;

    return json;
  }
}

Parameters

snapshot

Snapshot

options

any

args

...any[]

Returns

any

json

---

serializeAttribute()

Call Signature

static serializeAttribute(
   snapshot, 
   json, 
   key, 
   attribute): void;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:158

Parameters

snapshot

Snapshot

json

any

key

string

attribute

any

Returns

void

Call Signature

static serializeAttribute(
   snapshot, 
   json, 
   key, 
   attribute): void;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:492

Parameters

snapshot

any

json

any

key

any

attribute

any

Returns

void

---

serializeBelongsTo()

static serializeBelongsTo(
   snapshot, 
   json, 
   relationship): void;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:159

Parameters

snapshot

Snapshot

json

any

relationship

any

Returns

void

---

serializeHasMany()

static serializeHasMany(
   snapshot, 
   json, 
   relationship): void;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:160

Parameters

snapshot

Snapshot

json

any

relationship

any

Returns

void

---

serializeIntoHash()

readonly static serializeIntoHash(
   hash, 
   typeClass, 
   snapshot, 
   options): void;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:157

Parameters

hash

any

typeClass

Model

snapshot

Snapshot

options

any

Returns

void

---

serializePolymorphicType()

readonly static serializePolymorphicType(): void;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:161

Returns

void

---

shouldSerializeHasMany()

readonly static shouldSerializeHasMany(
   snapshot, 
   key, 
   relationship): boolean;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:155

Parameters

snapshot

Snapshot

key

string

relationship

RelationshipSchema

Returns

boolean

---

transformFor()

readonly static transformFor(attributeType, skipAssertion): Transform;

Defined in: warp-drive-packages/legacy/declarations/serializer/json-api.d.ts:167

Parameters

attributeType

string

skipAssertion

boolean

Returns

Transform