Embedded Records in Ember Data with JSON:API

July 21, 2019

Let’s say we have a GET /posts API endpoint and it returns the following JSON:API-ish response:

{
  "data": [
    {
      "id": "1",
      "type": "posts",
      "attributes": {
        "title": "Post A",
        "body": "...",
        "tags": [
          {
            "id": "1",
            "name": "JavaScript"
          },
          {
            "id": "2",
            "name": "Node.js"
          }
        ]
      }
    },
    {
      "id": "2",
      "type": "posts",
      "attributes": {
        "title": "Post B",
        "body": "...",
        "tags": [
          {
            "id": "1",
            "name": "JavaScript"
          },
          {
            "id": "3",
            "name": "Ember.js"
          }
        ]
      }
    }
  ]
}

In Ember Data, we’d probably want to model tags as a hasMany relationship to a post model:

import DS from 'ember-data';

const { Model, attr, hasMany } = DS;

export default Model.extend({
  title: attr('string'),
  tags: hasMany('tag', { async: false })
});

Unfortunately, this API isn’t responding with tags as a JSON:API relationship. What can we do? If you’re familiar with the EmbeddedRecordsMixin, you might think to try using that:

import DS from 'ember-data';

const { JSONAPISerializer, EmbeddedRecordsMixin } = DS;

export default JSONAPISerializer.extend(EmbeddedRecordsMixin, {
  attrs: {
    tags: {
      embedded: 'always'
    }
  }
});

However, this doesn’t work, since the JSONAPISerializer expects JSON:API relationships as opposed to nested attributes.

One approach to get this working would be to normalize the payload and turn tags into a JSON:API relationship, which means transforming the above payload into the following:

{
  "data": [
    {
      "id": "1",
      "type": "posts",
      "attributes": {
        "title": "Post A",
        "body": "..."
      },
      "relationships": {
        "tags": {
          "data": [
            {
              "id": "1",
              "type": "tags"
            },
            {
              "id": "2",
              "type": "tags"
            }
          ]
        }
      }
    },
    {
      "id": "2",
      "type": "posts",
      "attributes": {
        "title": "Post B",
        "body": "..."
      },
      "relationships": {
        "tags": {
          "data": [
            {
              "id": "1",
              "type": "tags"
            },
            {
              "id": "3",
              "type": "tags"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "id": "1",
      "type": "tags",
      "attributes": {
        "name": "JavaScript"
      }
    },
    {
      "id": "2",
      "type": "tags",
      "attributes": {
        "name": "Node.js"
      }
    },
    {
      "id": "3",
      "type": "tags",
      "attributes": {
        "name": "Ember.js"
      }
    }
  ]
}

We could do this by creating a custom post serializer that extends JSONAPISerializer and override the normalizeFindAllResponse method (assuming store.findAll('post') is being called):

ember g serializer post
// app/serializers/post.js
import DS from 'ember-data';

const { JSONAPISerializer } = DS;

export default JSONAPISerializer.extend({
  normalizeFindAllResponse(store, primaryModelClass, payload, id, requestType) {
    payload.data.forEach((resource) => {
      resource.relationships = {
        tags: {
          data: resource.attributes.tags.map((tag) => {
            return {
              id: tag.id,
              type: 'tags'
            };
          })
        }
      };
    });

    payload.included = payload.data
      .map((resource) => {
        return resource.attributes.tags;
      })
      .flat()
      .map((tag) => {
        let resource = {
          id: tag.id,
          type: 'tags'
        };

        delete tag.id;
        resource.attributes = tag;
        return resource;
      });

    return this._super(...arguments);
  }
});

Check out a demo if you’d like to see this in action.

What do you think? Personally I found this solution to be a lot of code to have to write and maintain.

If we look at the GET /posts response again, if we remove the keys data, type, and attributes, it looks pretty similar to the expected payload structure of the JSONSerializer. Although unconventional, why not try using the JSONSerializer alongside the JSONAPIAdapter instead of the JSONAPISerializer? By doing so, we can then leverage the EmbeddedRecordsMixin for tags. Let’s try it!

If you’d like to learn more about the different serializers, read my other blog post Which Ember Data Serializer Should I Use?.

// app/serializers/post.js
import DS from 'ember-data';

const { JSONSerializer, EmbeddedRecordsMixin } = DS;

export default JSONSerializer.extend(EmbeddedRecordsMixin, {
  attrs: {
    tags: {
      embedded: 'always'
    }
  },
  normalizeFindAllResponse(store, primaryModelClass, payload, id, requestType) {
    let newPayload = payload.data.map(({ id, attributes }) => {
      return { id, ...attributes };
    });

    return this._super(store, primaryModelClass, newPayload, id, requestType);
  }
});

I also need to create a serializer for the tag model that extends from JSONSerializer, since each tag in the payload follows the structure expected by that serializer:

ember g serializer tag
// app/serializers/tag.js
import DS from 'ember-data';

const { JSONSerializer } = DS;

export default JSONSerializer.extend();

Check out a demo if you’d like to see this in action.

What do you think? To me, it is less code and much simpler.

Here is another way we could implement the post serializer:

// app/serializers/post.js
import DS from 'ember-data';

const { JSONSerializer, EmbeddedRecordsMixin } = DS;

export default JSONSerializer.extend(EmbeddedRecordsMixin, {
  attrs: {
    tags: {
      embedded: 'always'
    }
  },
  normalize(typeClass, { id, attributes }) {
    return this._super(typeClass, { id, ...attributes });
  },
  normalizeFindAllResponse(store, primaryModelClass, payload, id, requestType) {
    return this._super(store, primaryModelClass, payload.data, id, requestType);
  }
});

Instead of mapping over the array in normalizeFindAllResponse as we did in our previous implementation, we can let Ember Data do that and just override the normalize hook which gets called for each resource. I think this approach might result in one less loop than our last implementation since we eliminated the map call, but I could be wrong. If anyone knows, please drop a line in the comments!

Conclusion

Ideally, this API would use a JSON:API relationship for tags. However, for one reason or another, I have run into this scenario enough times where relationships aren’t used and the API won’t be changed. Although unconventional, in these cases I found it useful to use the JSONSerializer alongside the JSONAPIAdapter instead of the JSONAPISerializer.

Ember Data in the Wild book cover

Have a custom API that you aren't sure how to use with Ember Data? Interested in writing your own adapter or serializer? Want to just know more about how Ember Data works? Check out my book Ember Data in the Wild - Getting Ember Data to Work With Your API .


Disclaimer: Any viewpoints and opinions expressed in this article are those of David Tang and do not reflect those of my employer or any of my colleagues.