- 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](https://github.com/plataformatec/devise/blob/e9c82472ffe7c43a448945f77e034a0e47dde0bb/lib/devise.rb),
[Refile](https://github.com/refile/refile/blob/6b24c293d044862dafbf1bfa4606672a64903aa2/lib/refile.rb) and
[Active Job](https://github.com/rails/rails/blob/30bacc26f8f258b39e12f63fe52389a968d9c1ea/activejob/lib/active_job.rb)
for example.

# Detailed design

## Require statement and main module

We are adding a extension for the Active Model, so
[following the Rubygens recomendation](http://guides.rubygems.org/name-your-gem/)
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](https://github.com/rails-api/active_model_serializers/tree/86fc7d7227f3ce538fcb28c1e8c7069ce311f0e1)
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](https://github.com/rails-api/active_model_serializers/pull/1301/files#r42963185)|
|`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.