How to Design Scalable and Maintainable Serializers in ActiveModel Serializers?

[ukmshi]

Hello! Thank you for creating such an amazing gem!

I’m currently facing an issue that I believe has been discussed in the past, but I couldn’t find any specific topics related to it. I’d like to ask for guidance on how others are addressing this challenge in the following use case.

Context

Model

erDiagram
    User ||--|{ Post : ""
    Post }|--|| Book : ""

Loading

Serializer

For models like the above, the serializers would typically look like this:

class UserSerializer < ActiveModelSerializers::Model
  attributes :id, :name, :post_count, :thumbnail

  has_many :posts, serializer: PostSerializer
end

class PostSerializer < ActiveModelSerializers::Model
  attributes :id, :comment, :rake

  belongs_to :user, serializer: UserSerializer
  belongs_to :book, serializer: BookSerializer
end

class BookSerializer < ActiveModelSerializers::Model
  attributes :id, :name, :avg_rate, :review_count, :book_image

  has_many :posts, serializer: PostSerializer
end

The Issue

The main challenge I’m facing is around the design and usage of serializers. Many articles I’ve seen tend to solve problems using a single, monolithic serializer. This approach often lacks clear separation of concerns and results in overly complex interdependencies. I’d like to know how others tackle the following issues:

Unnecessary Relationships in Different Use Cases

For example, in the /api/post/{:post_id} endpoint, I’d like the response to look like this:

{
    "id": 12345,
    "comment": "dummy text",
    "rate": 4.5,
    "user": {
        "id": 12345,
        "name": "jackson",
        "post_count": 15,
        "thumbnail": "http://xxxxxxxx.xxxxx/yyy"
    },
    "book": {
        "id": 435,
        "name": "The Little Prince",
        "avg_rate": 3.9,
        "review_count": 231,
        "book_image": "http://xxxxxxxx.xxxxx/xxx"
    }
}

However, for /api/book/{:book_id}, the response should look like this:

{
    "id": 435,
    "name": "The Little Prince",
    "avg_rate": 3.9,
    "review_count": 231,
    "book_image": "http://xxxxxxxx.xxxxx/xxx",
    "last_review": {
        "id": 12345,
        "comment": "dummy text",
        "rate": 4.5,
        "user": {
            "id": 12345,
            "name": "jackson",
            "post_count": 15,
            "thumbnail": "http://xxxxxxxx.xxxxx/yyy"
        }
    }
}

The problem becomes more apparent with endpoints like /api/book/{:book_id}/reviews or /api/book/{:book_id}/review/{:post_id}. In these cases, since the book is already identified by the endpoint, including the book details in every review unnecessarily duplicates data and adds noise to the response.

Sudden N+1 Query Issues

AMS often introduces N+1 query problems as new associations are added to models. For example, the /api/book/{:book_id}/reviews endpoint might be optimized like this:

class Api::Book::ReviewController < ActionController::Base
  def index
    book = Book.find_by(id: params[:book_id]).includes()
    raise NotFound if book.nil?

    @reviews = Review.where(book_id: book.id)
                     .includes(:user, :book)

    render json: @reviews, each_serializer: PostSerializer
  end
end

However, as the product grows, adding a new Author model and updating the serializer like this:

class PostSerializer < ActiveModelSerializers::Model
  attributes :id, :comment, :rate

  belongs_to :user, serializer: UserSerializer
  belongs_to :book, serializer: BookSerializer
  belongs_to :author, serializer: AuthorSerializer # new association
end

...suddenly introduces N+1 queries for Author in /api/book/{:book_id}/reviews. Since some legacy endpoints don’t use includes consistently, fixing this across the codebase can be challenging.

My Proposed Solution

One strength of AMS is its model-based approach. To maintain this advantage, I propose the following design:

class Base::PostSerializer < ActiveModelSerializers::Model
  attributes :id, :comment, :rate
end

class PostSerializer < Base::PostSerializer
  belongs_to :user, serializer: UserSerializer
  belongs_to :book, serializer: BookSerializer
end

class PostWithAuthorSerializer < Base::PostSerializer
  belongs_to :user, serializer: UserSerializer
  belongs_to :book, serializer: BookSerializer
  belongs_to :author, serializer: AuthorSerializer # specific to this use case
end

By defining a Base::PostSerializer for attributes and using separate serializers for specific use cases, we can minimize the impact on existing features. One key rule: never inherit from anything other than the base class to avoid complex, hard-to-manage hierarchies.

Final Question

How are you all addressing these kinds of design challenges with AMS? I’d love to hear your approaches and experiences. Thank you in advance!

[markbluhm]

This isn't exactly helpful, but, I would explore alternative gems as this was last updated 8yrs ago...

I am currently playing with panko serializer and they have some filters/context that could be valuable for you.

It is "more performance" - I quote that because I haven't gotten to compare before/after APM yet and there are differences in functionality between the two gems.

Lovely discovery yesterday, though, seems panko is deprecated in that it will still get some fixes/patches but no new features. I suppose that's fine by me as long as it's not totally abandoned but if you start to utilize a different serializer I'd be curious to hear about your choice and migration effort.

I'm curious if any of the filter stuff in AMS will skip the method call that does the lookup and then you can pass in a scope w/ appropriate filters...

Idk, I'm on my phone, sorry if that is a half assed AMS comment but I just wanted to suggest that depending on the size of your app you might see if there are any other serializers that give you simpler ways to address it.

Just kinda depends on how scalable you're trying to get

[ebaranowski]

@markbluhm You have to look at the version 10 stable branch. All dev work is there. They dont use master in this gem. It's in the repo Readme.