active_model_serializers/docs/general/serializers.md

Back to Guides

Serializers

Given a serializer class:

class SomeSerializer < ActiveModel::Serializer
end

The following methods may be defined in it:

Attributes

::attributes

Serialization of the resource title and body

In Serializer	#attributes
attributes :title, :body	{ title: 'Some Title', body: 'Some Body' }
attributes :title, :body def body "Special #{object.body}" end	{ title: 'Some Title', body: 'Special Some Body' }

::attribute

Serialization of the resource title

In Serializer	#attributes
attribute :title	{ title: 'Some Title' }
attribute :title, key: :name	{ name: 'Some Title' }
attribute :title { 'A Different Title'}	{ title: 'A Different Title' }
attribute :title def title 'A Different Title' end	{ title: 'A Different Title' }

PR please for conditional attributes:)

Associations

::has_one

e.g.

has_one :bio
has_one :blog, key: :site
has_one :maker, virtual_value: { id: 1 }

::has_many

e.g.

has_many :comments
has_many :comments, key: :reviews
has_many :comments, serializer: CommentPreviewSerializer
has_many :reviews, virtual_value: [{ id: 1 }, { id: 2 }]
has_many :comments, key: :last_comments do
  last(1)
end

::belongs_to

e.g.

belongs_to :author, serializer: AuthorPreviewSerializer
belongs_to :author, key: :writer
belongs_to :post
belongs_to :blog
def blog
  Blog.new(id: 999, name: 'Custom blog')
end

Caching

::cache

e.g.

cache key: 'post', expires_in: 0.1, skip_digest: true
cache expires_in: 1.day, skip_digest: true
cache key: 'writer', skip_digest: true
cache only: [:name], skip_digest: true
cache except: [:content], skip_digest: true
cache key: 'blog'
cache only: [:id]

#cache_key

e.g.

# Uses a custom non-time-based cache key
def cache_key
  "#{self.class.name.downcase}/#{self.id}"
end

Other

::type

e.g.

class UserProfileSerializer < ActiveModel::Serializer
  type 'profile'
end

::link

e.g.

link :other, 'https://example.com/resource'
link :self do
 href "https://example.com/link_author/#{object.id}"
end

#object

The object being serialized.

#root

PR please :)

#scope

PR please :)

#read_attribute_for_serialization(key)

The serialized value for a given key. e.g. read_attribute_for_serialization(:title) #=> 'Hello World'

#links

PR please :)

#json_key

PR please :)

Examples

Given two models, a Post(title: string, body: text) and a Comment(name: string, body: text, post_id: integer), you will have two serializers:

class PostSerializer < ActiveModel::Serializer
  cache key: 'posts', expires_in: 3.hours
  attributes :title, :body

  has_many :comments
end

and

class CommentSerializer < ActiveModel::Serializer
  attributes :name, :body

  belongs_to :post
end

Generally speaking, you, as a user of ActiveModelSerializers, will write (or generate) these serializer classes.

More Info

For more information, see the Serializer class on GitHub

Overriding association methods

If you want to override any association, you can use:

class PostSerializer < ActiveModel::Serializer
  has_many :comments

  def comments
    object.comments.active
  end
end

Overriding attribute methods

If you want to override any attribute, you can use:

class PostSerializer < ActiveModel::Serializer
  attributes :body

  def body
    object.body.downcase
  end
end