active_model_serializers/docs/rfcs/0000-namespace.md

• Start Date: (2015-10-29)
• RFC PR: (leave this empty)
• AMS Issue: (leave this empty)

Summary

Provide a consistent API for the user of the AMS.

Motivation

The actual public API is defined under ActiveModelSerializers, ActiveModel::Serializer and ActiveModel.

At the ActiveModel::Serializer we have:

• ActiveModel::Serializer.config
• ActiveModel::Serializer

At the ActiveModelSerializers we have:

• ActiveModelSerializers::Model
• ActiveModelSerializers.logger

At ActiveModel we have:

• ActiveModel::SerializableResource

The idea here is to provide a single namespace ActiveModel::Serializers to the user. Following the same idea we have on other gems like Devise, Refile and Active Job for example.

Detailed design

Require statement and main module

We are adding a extension for the Active Model, so following the Rubygens recomendation for the gem name we need to change to this.

Gem name	Require statement	Main class or module
active_model_serializers	active_model/serializers	ActiveModel::Serializers

The expected gem name, in the gemspec is active_model-serializers but we don't need to change this, we can change the code without the need of a new gem on Rubygems.

Active Model for example follow the same idea the gem name on gemspec is activemodel and to the end user is:

Gem name	Require statement	Main class or module
activemodel	active_model	ActiveModel

As you can see we do not require activemodel(the gem name in gemspec) insted we use active_model.

And based on the bump of 0.10.0.pre released by Steve Klabnik if we take a look on README and gemspec always is used ActiveModel::Serializers.

New classes and modules organization

Since this will be a big change we can do this on baby steps, read small PRs. A possible approach is:

• Create the ActiveModel::Serializers namespace;
• Move all content under ActiveModelSerializers to be under ActiveModel::Serializers, the logger is on this step;
• Move all content under ActiveModel::Serializer to be under ActiveModel::Serializers, the adapter is on this steps;
• Move all content under ActiveModel to be under ActiveModel::Serializers, the SerializableResource is on this step;
• Now that all the code lives under ActiveModel::Serializers we can:
  • create a better name to the ActiveModel::Serializers::Serializer keeping in mind only to keep this in the same namespace
  • create a better name to the ActiveModel::Serializers::Serializer::Adapter::JsonApi probably remove this from the ActiveModel::Serializers::Serializer and do something like ActiveModel::Serializers::Adapter::JsonApi keeping in mind only to keep this in the same namespace
  • Change all public API that doesn't make sense, keeping in mind only to keep this in the same namespace
• Update the README;
• Update the docs;

The following table represents the current and the desired classes and modules at the first moment.

Current	Desired	Notes
ActiveModelSerializers and ActiveModel::Serializer	ActiveModel::Serializers	The main namespace
ActiveModelSerializers.logger	ActiveModel::Serializers.logger
ActiveModelSerializers::Model	ActiveModel::Serializers::Model
ActiveModel::SerializableResource	ActiveModel::Serializers::SerializableResource
ActiveModel::Serializer	ActiveModel::Serializers::Serializer	I know that is probably a bad name, but In a second moment we can rename this to Resource for example following this idea
ActiveModel::Serializer.config	ActiveModel::Serializers.config

Drawbacks

This will be a breaking change, so all users serializers will be broken. All PRs will need to rebase since the architeture will change a lot.

Alternatives

We can keep the way it is, and keep in mind to not add another namespace as a public API.

Or we can start moving the small ones that seems to be the ActiveModelSerializers and ActiveModel and later we can handle the ActiveModel::Serializer.

Unresolved questions

What is the better class name to be used to the class that will be inherited at the creation of a serializer.