JSONAPISerializer

The JSONAPISerializer. Subclass of Serializer.

Properties

alwaysIncludeLinkageData: Boolean

By default, JSON:API's linkage data is only added for relationships that are being included in the current request.

That means given an author model with a posts relationship, a GET request to /authors/1 would return a JSON:API document with an empty relationships hash:

{
  data: {
    type: 'authors',
    id: '1',
    attributes: { ... }
  }
}

but a request to GET /authors/1?include=posts would have linkage data added (in addition to the included resources):

{
  data: {
    type: 'authors',
    id: '1',
    attributes: { ... },
    relationships: {
      data: [
        { type: 'posts', id: '1' },
        { type: 'posts', id: '2' },
        { type: 'posts', id: '3' }
      ]
    }
  },
  included: [ ... ]
}

To add the linkage data for all relationships, you could set alwaysIncludeLinkageData to true:

JSONAPISerializer.extend({
  alwaysIncludeLinkageData: true
});

Then, a GET to /authors/1 would respond with

{
  data: {
    type: 'authors',
    id: '1',
    attributes: { ... },
    relationships: {
      posts: {
        data: [
          { type: 'posts', id: '1' },
          { type: 'posts', id: '2' },
          { type: 'posts', id: '3' }
        ]
      }
    }
  }
}

even though the related posts are not included in the same document.

You can also use the links method (on the Serializer base class) to add relationship links (which will always be added regardless of the relationship is being included document), or you could use shouldIncludeLinkageData for more granular control.

For more background on the behavior of this API, see this blog post.

Methods

keyForAttribute(attr: String): String

Used to customize the key for an attribute. By default, compound attribute names are dasherized.

For example, the JSON:API document for a post model with a commentCount attribute would be:

{
  data: {
    id: 1,
    type: 'posts',
    attributes: {
      'comment-count': 28
    }
  }
}

keyForRelationship(key: String): String

Used to customize the key for a relationships. By default, compound relationship names are dasherized.

For example, the JSON:API document for an author model with a blogPosts relationship would be:

{
  data: {
    id: 1,
    type: 'author',
    attributes: {
      ...
    },
    relationships: {
      'blog-posts': {
        ...
      }
    }
  }
}

Use this hook to add top-level links data to JSON:API resource objects. The argument is the model being serialized.

// serializers/author.js
import { JSONAPISerializer } from 'miragejs';

export default JSONAPISerializer.extend({

  links(author) {
    return {
      'posts': {
        related: `/api/authors/${author.id}/posts`
      }
    };
  }

});

shouldIncludeLinkageData(relationshipKey: String, model: Model): Boolean

Allows for per-relationship inclusion of linkage data. Use this when alwaysIncludeLinkageData is not granular enough.

export default JSONAPISerializer.extend({
  shouldIncludeLinkageData(relationshipKey, model) {
    if (relationshipKey === 'author' || relationshipKey === 'ghostWriter') {
      return true;
    }
    return false;
  }
});

typeKeyForModel(model: Model): String

Used to customize the type field of the document. By default, pluralizes and dasherizes the model's modelName.

For example, the JSON:API document for a blogPost model would be:

{
  data: {
    id: 1,
    type: 'blog-posts'
  }
}