Appearance

Documentation / @ember-data/serializer / rest / default

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

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

Normally, applications will use the RESTSerializer by implementing the normalize method.

This allows you to do whatever kind of munging you need and is especially useful if your server is inconsistent and you need to do munging differently for many different kinds of responses.

See the normalize documentation for more information.

Across the Board Normalization ​

There are also a number of hooks that you might find useful to define across-the-board rules for your payload. These rules will be useful if your server is consistent, or if you're building an adapter for an infrastructure service, like Firebase, and want to encode service conventions.

For example, if all of your keys are underscored and all-caps, but otherwise consistent with the names you use in your models, you can implement across-the-board rules for how to convert an attribute name in your model to a key in your JSON.

app/serializers/application.js
js
import { RESTSerializer } from '@warp-drive/legacy/serializer/rest';
import { underscore } from '<app-name>/utils/string-utils';

export default class ApplicationSerializer extends RESTSerializer {
  keyForAttribute(attr, method) {
    return underscore(attr).toUpperCase();
  }
}

You can also implement keyForRelationship, which takes the name of the relationship as the first parameter, the kind of relationship (hasMany or belongsTo) as the second parameter, and the method (serialize or deserialize) as the third parameter.

RESTSerializer

Constructors ​

Constructor ​

ts
new default(owner?): default;

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

Parameters ​

owner? ​

any

Returns ​

default

Properties ​

store ​

ts
store: default;

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

mergedProperties ​

ts
readonly static mergedProperties: any;

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

primaryKey ​

ts
readonly static primaryKey: string;

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

Methods ​

normalize() ​

ts
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:

js
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() ​

ts
readonly static _canSerialize(key): boolean;

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

Parameters ​

key ​

string

Returns ​

boolean

_getMappedKey() ​

ts
readonly static _getMappedKey(key, modelClass): string;

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

Parameters ​

key ​

string

modelClass ​

any

Returns ​

string

_mustSerialize() ​

ts
readonly static _mustSerialize(key): boolean;

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

Parameters ​

key ​

string

Returns ​

boolean

_normalizePolymorphicRecord() ​

ts
static _normalizePolymorphicRecord(
   store, 
   hash, 
   prop, 
   primaryModelClass, 
   primarySerializer): any;

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

Parameters ​

store ​

any

hash ​

any

prop ​

any

primaryModelClass ​

any

primarySerializer ​

any

Returns ​

any

_normalizeResponse() ​

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

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

Parameters ​

store ​

Store

primaryModelClass ​

Model

payload ​

any

id ​

string | number

requestType ​

string

isSingle ​

boolean

Returns ​

any

applyTransforms() ​

ts
readonly static applyTransforms(typeClass, data): any;

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

Parameters ​

typeClass ​

Model

data ​

any

Returns ​

any

extractAttributes() ​

ts
readonly static extractAttributes(modelClass, resourceHash): any;

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

Parameters ​

modelClass ​

any

resourceHash ​

any

Returns ​

any

extractErrors() ​

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

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

Parameters ​

store ​

Store

typeClass ​

Model

payload ​

any

id ​

string | number

Returns ​

any

extractId() ​

ts
readonly static extractId(modelClass, resourceHash): string;

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

Parameters ​

modelClass ​

any

resourceHash ​

any

Returns ​

string

extractMeta() ​

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

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

Parameters ​

store ​

Store

modelClass ​

Model

payload ​

any

Returns ​

any

extractPolymorphicRelationship() ​

Call Signature ​

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

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

Parameters ​
relationshipModelName ​

any

relationshipHash ​

any

relationshipOptions ​

any

Returns ​

any

Call Signature ​

ts
static extractPolymorphicRelationship(
   relationshipType, 
   relationshipHash, 
   relationshipOptions, ...
   args): any;

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

You can use this method to customize how a polymorphic relationship should be extracted.

Parameters ​
relationshipType ​

any

relationshipHash ​

any

relationshipOptions ​

any

args ​

...any[]

Returns ​

any

extractRelationship() ​

ts
readonly static extractRelationship(relationshipModelName, relationshipHash): any;

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

Parameters ​

relationshipModelName ​

any

relationshipHash ​

any

Returns ​

any

extractRelationships() ​

ts
readonly static extractRelationships(modelClass, resourceHash): any;

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

Parameters ​

modelClass ​

any

resourceHash ​

any

Returns ​

any

isPrimaryType() ​

ts
static isPrimaryType(
   store, 
   modelName, 
   primaryModelClass): boolean;

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

Parameters ​

store ​

any

modelName ​

any

primaryModelClass ​

any

Returns ​

boolean

keyForAttribute() ​

ts
readonly static keyForAttribute(key, method): string;

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

Parameters ​

key ​

string

method ​

string

Returns ​

string

ts
readonly static keyForLink(key, kind): string;

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

Parameters ​

key ​

string

kind ​

string

Returns ​

string

keyForPolymorphicType() ​

ts
static keyForPolymorphicType(
   key, 
   typeClass, 
   method): string;

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

keyForPolymorphicType can be used to define a custom key when serializing and deserializing a polymorphic type. By default, the returned key is ${key}Type.

Example

app/serializers/post.js
js
import { RESTSerializer } from '@warp-drive/legacy/serializer/rest';

export default class ApplicationSerializer extends RESTSerializer {
  keyForPolymorphicType(key, relationship) {
    let relationshipKey = this.keyForRelationship(key);

    return 'type-' + relationshipKey;
  }
}

Parameters ​

key ​

string

typeClass ​

string

method ​

string

Returns ​

string

normalized key

keyForRelationship() ​

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

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

Parameters ​

key ​

string

typeClass ​

string

method ​

string

Returns ​

string

modelNameFromPayloadKey() ​

ts
static modelNameFromPayloadKey(key): string;

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

Parameters ​

key ​

string

Returns ​

string

normalize() ​

ts
readonly static normalize(modelClass, resourceHash): any;

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

Parameters ​

modelClass ​

any

resourceHash ​

any

Returns ​

any

normalizeArrayResponse() ​

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

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

Parameters ​

store ​

Store

primaryModelClass ​

Model

payload ​

any

id ​

string | number

requestType ​

string

Returns ​

any

normalizeCreateRecordResponse() ​

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

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

Parameters ​

store ​

Store

primaryModelClass ​

Model

payload ​

any

id ​

string | number

requestType ​

string

args ​

...any[]

Returns ​

any

normalizeDeleteRecordResponse() ​

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

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

Parameters ​

store ​

Store

primaryModelClass ​

Model

payload ​

any

id ​

string | number

requestType ​

string

args ​

...any[]

Returns ​

any

normalizeFindAllResponse() ​

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

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

Parameters ​

store ​

Store

primaryModelClass ​

Model

payload ​

any

id ​

string | number

requestType ​

string

args ​

...any[]

Returns ​

any

normalizeFindBelongsToResponse() ​

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

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

Parameters ​

store ​

Store

primaryModelClass ​

Model

payload ​

any

id ​

string | number

requestType ​

string

args ​

...any[]

Returns ​

any

normalizeFindHasManyResponse() ​

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

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

Parameters ​

store ​

Store

primaryModelClass ​

Model

payload ​

any

id ​

string | number

requestType ​

string

args ​

...any[]

Returns ​

any

normalizeFindManyResponse() ​

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

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

Parameters ​

store ​

Store

primaryModelClass ​

Model

payload ​

any

id ​

string | number

requestType ​

string

args ​

...any[]

Returns ​

any

normalizeFindRecordResponse() ​

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

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

Parameters ​

store ​

Store

primaryModelClass ​

Model

payload ​

any

id ​

string | number

requestType ​

string

args ​

...any[]

Returns ​

any

normalizeQueryRecordResponse() ​

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

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

Parameters ​

store ​

Store

primaryModelClass ​

Model

payload ​

any

id ​

string | number

requestType ​

string

args ​

...any[]

Returns ​

any

normalizeQueryResponse() ​

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

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

Parameters ​

store ​

Store

primaryModelClass ​

Model

payload ​

any

id ​

string | number

requestType ​

string

args ​

...any[]

Returns ​

any

normalizeRelationships() ​

ts
readonly static normalizeRelationships(typeClass, hash): void;

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

Parameters ​

typeClass ​

any

hash ​

any

Returns ​

void

normalizeResponse() ​

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

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

Parameters ​

store ​

Store

primaryModelClass ​

Model

payload ​

any

id ​

string | number

requestType ​

string

args ​

...any[]

Returns ​

any

normalizeSaveResponse() ​

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

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

Parameters ​

store ​

Store

primaryModelClass ​

Model

payload ​

any

id ​

string | number

requestType ​

string

args ​

...any[]

Returns ​

any

normalizeSingleResponse() ​

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

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

Parameters ​

store ​

Store

primaryModelClass ​

Model

payload ​

any

id ​

string | number

requestType ​

string

Returns ​

any

normalizeUpdateRecordResponse() ​

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

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

Parameters ​

store ​

Store

primaryModelClass ​

Model

payload ​

any

id ​

string | number

requestType ​

string

args ​

...any[]

Returns ​

any

normalizeUsingDeclaredMapping() ​

ts
readonly static normalizeUsingDeclaredMapping(modelClass, hash): void;

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

Parameters ​

modelClass ​

any

hash ​

any

Returns ​

void

payloadKeyFromModelName() ​

ts
static payloadKeyFromModelName(modelName): string;

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

You can use payloadKeyFromModelName to override the root key for an outgoing request. By default, the RESTSerializer returns a camelized version of the model's name.

For a model called TacoParty, its modelName would be the string taco-party. The RESTSerializer will send it to the server with tacoParty as the root key in the JSON payload:

js
{
  "tacoParty": {
    "id": "1",
    "location": "Matthew Beale's House"
  }
}

For example, your server may expect dasherized root objects:

app/serializers/application.js
js
import { RESTSerializer } from '@warp-drive/legacy/serializer/rest';
import { dasherize } from '<app-name>/utils/string-utils';

export default class ApplicationSerializer extends RESTSerializer {
  payloadKeyFromModelName(modelName) {
    return dasherize(modelName);
  }
}

Given a TacoParty model, calling save on it would produce an outgoing request like:

js
{
  "taco-party": {
    "id": "1",
    "location": "Matthew Beale's House"
  }
}

Parameters ​

modelName ​

string

Returns ​

string

pushPayload() ​

ts
static pushPayload(store, payload): void;

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

This method allows you to push a payload containing top-level collections of records organized per type.

js
{
  "posts": [{
    "id": "1",
    "title": "Rails is omakase",
    "author", "1",
    "comments": [ "1" ]
  }],
  "comments": [{
    "id": "1",
    "body": "FIRST"
  }],
  "users": [{
    "id": "1",
    "name": "@d2h"
  }]
}

It will first normalize the payload, so you can use this to push in data streaming in from your server structured the same way that fetches and saves are structured.

Parameters ​

store ​

Store

payload ​

any

Returns ​

void

serialize() ​

Call Signature ​

ts
static serialize(snapshot, options): any;

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

Parameters ​
snapshot ​

Snapshot

options ​

any

Returns ​

any

Call Signature ​

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

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

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

By default, it creates a JSON object with a key for each attribute and belongsTo relationship.

For example, consider this model:

app/models/comment.js
js
import Model, { attr, belongsTo } from '@ember-data/model';

export default class Comment extends Model {
  @attr title
  @attr body

  @belongsTo('user') author
}

The default serialization would create a JSON object like:

js
{
  "title": "Rails is unagi",
  "body": "Rails? Omakase? O_O",
  "author": 12
}

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 JSON hash.

By default, belongs-to relationships are converted into IDs when inserted into the JSON hash.

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 adapter passes in includeId: true when serializing a record for createRecord, but not for updateRecord.

Customization ​

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

In that case, you can implement serialize yourself and return a JSON hash of your choosing.

app/serializers/post.js
js
import { RESTSerializer } from '@warp-drive/legacy/serializer/rest';

export default class ApplicationSerializer extends RESTSerializer {
  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
js
import { RESTSerializer } from '@warp-drive/legacy/serializer/rest';
import { pluralize } from '<app-name>/utils/string-utils';

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

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

    snapshot.eachRelationship(function(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 attribute.underscore().toUpperCase();
}

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

This serializer will generate JSON that looks like this:

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

Tweaking the Default JSON ​

If you just want to do some small tweaks on the default JSON, you can call super first and make the tweaks on the returned JSON.

app/serializers/post.js
js
import { RESTSerializer } from '@warp-drive/legacy/serializer/rest';

export default class ApplicationSerializer extends RESTSerializer {
  serialize(snapshot, options) {
    let json = super.serialize(snapshot, options);

    json.subject = json.title;
    delete json.title;

    return json;
  }
}
Parameters ​
snapshot ​

Snapshot

options ​

any

args ​

...any[]

Returns ​

any

json

serializeAttribute() ​

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

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

Parameters ​

snapshot ​

Snapshot

json ​

any

key ​

string

attribute ​

any

Returns ​

void

serializeBelongsTo() ​

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

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

Parameters ​

snapshot ​

Snapshot

json ​

any

relationship ​

any

Returns ​

void

serializeHasMany() ​

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

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

Parameters ​

snapshot ​

Snapshot

json ​

any

relationship ​

any

Returns ​

void

serializeIntoHash() ​

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

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

Parameters ​

hash ​

any

typeClass ​

Model

snapshot ​

Snapshot

options ​

any

Returns ​

void

serializePolymorphicType() ​

Call Signature ​

ts
static serializePolymorphicType(): void;

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

Returns ​

void

Call Signature ​

ts
static serializePolymorphicType(
   snapshot, 
   json, 
   relationship): void;

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

You can use this method to customize how polymorphic objects are serialized. By default the REST Serializer creates the key by appending Type to the attribute and value from the model's camelcased model name.

Parameters ​
snapshot ​

Snapshot

json ​

any

relationship ​

any

Returns ​

void

shouldSerializeHasMany() ​

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

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

Parameters ​

snapshot ​

Snapshot

key ​

string

relationship ​

RelationshipSchema

Returns ​

boolean

transformFor() ​

ts
readonly static transformFor(attributeType, skipAssertion): Transform;

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

Parameters ​

attributeType ​

string

skipAssertion ​

boolean

Returns ​

Transform

Released under the MIT License.

Copyright © 2025 Ember.js and Contributors