In this chapter, we will look at polymorphism and how it relates to Ember Data. If we look up the definition of polymorphism as it relates to programming, we’ll see it described as “the ability of an object to take on many forms.” For example, a product could come in the form of a book or a course. In an Ember application, we would have a book model and a course model that extend from a base product model. If we extend the definition of polymorphism to relationships in our Ember Data models, it means our relationships can hold objects of different types that share a common interface, like inheriting from the same product model. Let’s look at the two examples we’ll be covering in this chapter.
Example 1 – Purchased Products
Imagine we have a site where users can purchase different products like courses and books. We would create a course model and a book model that extend from a base product model. We would also have a user model to represent the current user. Typically with these types of sites, there is a page that lists all of the products that the authenticated user has purchased. We could express the relationship between a user and the various products that they purchased as a hasMany relationship.
Going back to the definition of polymorphism, a user’s purchased products can take on multiple forms such as a course or a book. This is an example of a polymorphic hasMany relationship, because the relationship can contain records of multiple types that all inherit from a base product class.
Example 2 – Content with Comments
Let’s say our application also offers content in the form of blog posts and videos. We want users to be able to comment on each of these types of content. As such, we’ll have a post model and a video model that extend from a base content model. We’ll also have a comment model. Posts and videos can have many comments. A comment however can belong to a single piece of content, which in our application can be a post or a video. We could express this relationship between the comment and the content as a polymorphic belongsTo relationship, because the content associated with a comment can be of different types as long as the record inherits from our base content class.
Now that we have a few conceptual examples, let’s see how we can implement this data model in Ember Data.
Setup
I have created a simple application that implements the preceding examples. The code for this application can be found in the chapter-13-restserializer folder of the source code for this book. We will use this application as a way of testing our model definitions and polymorphic relationships.
Similar to previous chapters, the API is mocked using Ember CLI Mirage.1 In this chapter, our mock API will be following the RESTSerializer conventions, but the patterns and techniques covered also apply to APIs that follow the JSONSerializer and JSONAPISerializer conventions with some minor differences. If you’d like to see the code for the application when using the JSONSerializer, take a look at the chapter-13-jsonserializer folder of the source code for this book. If you’d like to see the code for the application when using the JSONAPISerializer, take a look at the chapter-13-jsonapiserializer folder of the source code for this book.
Polymorphic “hasMany” Relationships
As mentioned earlier, our course and book models will extend from a base product model which contains functionality common among all products, like having a title attribute.
The purchasedProducts relationship is a standard hasMany relationship but with a polymorphic option. This will allow us to store records of different types as long as they extend from the product model. I have made this a synchronous relationship in the example application, but the relationship could have been asynchronous.
Next, let’s look at the expected response payload if we were to fetch a user who has purchased products. Again, our mock API will be following the RESTSerializer conventions.
As we learned in Chapter 3 – API Response Formats and Serializers, when using the RESTSerializer or the JSONSerializer , hasMany relationships should be represented in API payloads as an array of IDs. In order to use polymorphic relationships, purchasedProducts must be an array of JSON:API Resource Identifier Objects, that is, objects with id and type properties. The type property corresponds to the name of an Ember Data model in either the singular or plural form, which in this case is either course or book.
With this API response, our purchasedProducts hasMany relationship will be polymorphic. That is, purchasedProducts can contain course records and book records.
The only requirement here is that we need to include a type property in each product resource, which corresponds to the model name of a “product” subclass.
Polymorphic “belongsTo” Relationships
Our post and video models will extend from a base content model which contains the comments relationship.
The content relationship is a standard belongsTo relationship but with a polymorphic option. This will allow us to assign different types of content records to the content relationship as long as those records inherit from the content model.
Notice how each resource under comments contains a JSON:API Resource Identifier Object under the content property. Similar to the polymorphic hasMany relationship, the id and type will be used to establish a belongsTo relationship with the correct content subclass record.
Customizing Polymorphic Relationship Serialization
In the last two sections, we learned how to define our models and the expected response formats so that hasMany and belongsTo polymorphic relationships get wired up correctly. Now we will look at how to customize a serializer for when an API doesn’t follow the default conventions for polymorphic relationships.
This serialized payload is similar to what we’d expect when serializing any belongsTo relationship, except there is a new key, contentType. The default behavior of the RESTSerializer when serializing polymorphic belongsTo relationships is to create a key where “Type” is appended to the name of the polymorphic relationship. In this case, our polymorphic relationship is named content so the new key becomes contentType.
Then, we override the comment.content property to be { id: '1', type: 'post' } and delete the comment.contentType property.
As we learned in previous chapters, we could also add this logic to a serializer’s serialize() method, but using the keyForPolymorphicType() and serializePolymorphicType() methods will likely reduce the amount of code needed for polymorphic relationship serialization.
Customizing Polymorphic Relationship Normalization
I know this example is a bit contrived, but you never know what kinds of APIs you’ll see in the wild! Before, content contained a JSON:API Resource Identifier Object such as { "id": "1", "type": "post" }. How can we normalize our polymorphic content relationship? We can override one of the many normalization methods that we covered in previous chapters, or we can override the extractPolymorphicRelationship() method. This method gets called for relationships declared with the polymorphic: true option and returns a JSON:API Resource Identifier Object.
In the implementation earlier, relationshipHash will contain post:1 and video:2 for the preceding response. We can split on the colon and create a new object that matches the structure of a JSON:API Resource Identifier Object and return that in the scenario where our custom polymorphic relationship convention is used. Otherwise, we will let the default polymorphic extraction behavior run via super.extractPolymorphicRelationship(...arguments).
Summary
Polymorphism is a powerful concept that allows us to have models that relate to each other through inheritance, and Ember Data relationships can support this. This ultimately allows a belongsTo relationship to contain records of different types through a single relationship as long as those records inherit from a common base class. This also allows for a hasMany relationship to contain records of multiple types as long as those records inherit from a common base class.
In this chapter, we looked at how to set up our models and API to support polymorphic relationships. We then looked at how we can customize serialization and normalization of polymorphic relationships if our API doesn’t follow the default conventions that Ember Data expects. Even though we looked at the implementation of polymorphic relationships with the RESTSerializer, the model definitions are the same if you are using one of the other built-in serializers. Additionally, the serializer methods that we overrode are the same, except the JSONSerializer and JSONAPISerializer don’t support the keyForPolymorphicType() method. There are also some slight differences in the default API conventions for the JSONSerializer and the JSONAPISerializer. Despite these minor differences, the patterns and techniques covered in this chapter should equip you to handle polymorphic relationships regardless of which serializer your application is using.
Well, this is the end. Thanks for reading my book! Hopefully, this has helped you and has put you in a good position to work with Ember Data and any custom API. If you have any questions, please reach out to me on Twitter @iamdtang or by email at [email protected]. I would love to hear about your experiences with Ember Data. You can also stay up to date with my Ember adventures on my blog at https://davidtang.io.