Class EmbeddedRecordsMixin

Normalize the record and recursively normalize/extract all the embedded records while pushing them into the store as they are encountered

A payload with an attr configured for embedded records needs to be extracted:

{
  "post": {
    "id": "1"
    "title": "Rails is omakase",
    "comments": [{
      "id": "1",
      "body": "Rails is unagi"
    }, {
      "id": "2",
      "body": "Omakase O_o"
    }]
  }
}

When serializing an embedded record, modify the property (in the JSON payload) that refers to the parent record (foreign key for the relationship).

Serializing a belongsTo relationship removes the property that refers to the parent record

Serializing a hasMany relationship does not remove the property that refers to the parent record.

Serialize belongsTo relationship when it is configured as an embedded object.

This example of an author model belongs to a post model:

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

Post = Model.extend({
  title:    attr('string'),
  body:     attr('string'),
  author:   belongsTo('author')
});

Author = Model.extend({
  name:     attr('string'),
  post:     belongsTo('post')
});

Use a custom (type) serializer for the post model to configure embedded author

import RESTSerializer, { EmbeddedRecordsMixin } from '@ember-data/serializer/rest';

export default class PostSerializer extends RESTSerializer.extend(EmbeddedRecordsMixin) {
  attrs = {
    author: { embedded: 'always' }
  }
}

A payload with an attribute configured for embedded records can serialize the records together under the root attribute's payload:

{
  "post": {
    "id": "1"
    "title": "Rails is omakase",
    "author": {
      "id": "2"
      "name": "dhh"
    }
  }
}

Serializes hasMany relationships when it is configured as embedded objects.

This example of a post model has many comments:

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

Post = Model.extend({
  title:    attr('string'),
  body:     attr('string'),
  comments: hasMany('comment')
});

Comment = Model.extend({
  body:     attr('string'),
  post:     belongsTo('post')
});

Use a custom (type) serializer for the post model to configure embedded comments

import RESTSerializer, { EmbeddedRecordsMixin } from '@ember-data/serializer/rest';

export default class PostSerializer extends RESTSerializer.extend(EmbeddedRecordsMixin) {
  attrs = {
    comments: { embedded: 'always' }
  }
}

A payload with an attribute configured for embedded records can serialize the records together under the root attribute's payload:

{
  "post": {
    "id": "1"
    "title": "Rails is omakase",
    "body": "I want this for my ORM, I want that for my template language..."
    "comments": [{
      "id": "1",
      "body": "Rails is unagi"
    }, {
      "id": "2",
      "body": "Omakase O_o"
    }]
  }
}

The attrs options object can use more specific instruction for extracting and serializing. When serializing, an option to embed ids, ids-and-types or records can be set. When extracting the only option is records.

So { embedded: 'always' } is shorthand for: { serialize: 'records', deserialize: 'records' }

To embed the ids for a related object (using a hasMany relationship):

import RESTSerializer, { EmbeddedRecordsMixin } from '@ember-data/serializer/rest';

export default class PostSerializer extends RESTSerializer.extend(EmbeddedRecordsMixin) {
  attrs = {
    comments: { serialize: 'ids', deserialize: 'records' }
  }
}

{
  "post": {
    "id": "1"
    "title": "Rails is omakase",
    "body": "I want this for my ORM, I want that for my template language..."
    "comments": ["1", "2"]
  }
}

To embed the relationship as a collection of objects with id and type keys, set ids-and-types for the related object.

This is particularly useful for polymorphic relationships where records don't share the same table and the id is not enough information.

For example having a user that has many pets:

User = Model.extend({
  name: attr('string'),
  pets: hasMany('pet', { polymorphic: true })
});

Pet = Model.extend({
  name: attr('string'),
});

Cat = Pet.extend({
  // ...
});

Parrot = Pet.extend({
  // ...
});

import RESTSerializer, { EmbeddedRecordsMixin } from '@ember-data/serializer/rest';

export default class UserSerializer extends RESTSerializer.extend(EmbeddedRecordsMixin) {
  attrs = {
    pets: { serialize: 'ids-and-types', deserialize: 'records' }
  }
}

{
  "user": {
    "id": "1"
    "name": "Bertin Osborne",
    "pets": [
      { "id": "1", "type": "Cat" },
      { "id": "1", "type": "Parrot"}
    ]
  }
}