ActiveModelSerializers

About

ActiveModelSerializers works through two components: serializers and adapters.

Serializers describe which attributes and relationships should be serialized.

Adapters describe how attributes and relationships should be serialized.

SerializableResource co-ordinates the resource, Adapter and Serializer to produce the
resource serialization. The serialization has the #as_json, #to_json and #serializable_hash
methods used by the Rails JSON Renderer. (SerializableResource actually delegates
these methods to the adapter.)

By default ActiveModelSerializers will use the Attributes Adapter (no JSON root).
But we strongly advise you to use JsonApi Adapter, which
follows 1.0 of the format specified in jsonapi.org/format.
Check how to change the adapter in the sections below.

ActiveModel::Serializer

An **ActiveModel::Serializer** wraps a serializable resource
and exposes an attributes method, among a few others.
It allows you to specify which attributes and associations should be represented in the serializatation of the resource.
It requires an adapter to transform its attributes into a JSON document; it cannot be serialized itself.
It may be useful to think of it as a
presenter.

ActiveModel::CollectionSerializer

The ActiveModel::CollectionSerializer represents a collection of resources as serializers
and, if there is no serializer, primitives.

ActiveModelSerializers::Adapter::Base

The **ActiveModelSerializeres::Adapter::Base** describes the structure of the JSON document generated from a
serializer. For example, the Attributes example represents each serializer as its
unmodified attributes. The JsonApi adapter represents the serializer as a JSON
API document.

ActiveModelSerializers::SerializableResource

The **ActiveModelSerializers::SerializableResource** acts to coordinate the serializer(s) and adapter
to an object that responds to to_json, and as_json. It is used in the controller to
encapsulate the serialization resource when rendered. However, it can also be used on its own
to serialize a resource outside of a controller, as well.

Primitive handling

Definitions: A primitive is usually a String or Array. There is no serializer
defined for them; they will be serialized when the resource is converted to JSON (as_json or
to_json). (The below also applies for any object with no serializer.)

Internally, if no serializer can be found in the controller, the resource is not decorated by
ActiveModelSerializers.

However, when a primitive value is an attribute or in a collection, it is not modified.

When serializing a collection and the collection serializer (CollectionSerializer) cannot
identify a serializer for a resource in its collection, it throws :no_serializer.
For example, when caught by Reflection#build_association, and the association value is set directly:

ActiveModel::Serializer#attributes is used by the adapter to get the attributes for
resource as defined by the serializer.

(In Rails, the options are also passed to the as_json(options) or to_json(options)
methods on the resource serialization by the Rails JSON renderer. They are, therefore, important
to know about, but not part of ActiveModelSerializers.)