grape-active_model_serializers/UPGRADING.md

### Upgrading to v1.5.0

#### ASM v0.10.x support added, v0.9.x support dropped

[ASM](https://github.com/rails-api/active_model_serializers) introduced
breaking changes with ASM v0.10.x. Support has been introduced in v1.5.0.
If you require support for older version of ASM, please lock your Gemfile
to the relevant version.

#### Non-collection Serializer Resolution

Serializer resolution now uses the following strategy:

1. Defined by the resource

```
class UsersApi < Grape::Api
  resource :users do
    get '/:id', serializer: SpecifiedUserSerializer do
      current_user
    end
  end
end

class User
  def serializer_class
    SpecifiedUserSerializer
  end
end
```

2. Specified by options

```
class UsersApi < Grape::Api
  resource :users do
    get '/:id', serializer: SpecifiedUserSerializer do
      current_user
    end
  end
end
```

2. Namespace inferred

```
class V1::UsersApi < Grape::Api
  resource :users do
    get '/:id' do
      current_user
    end
  end
end
# 'V1::UsersApi'.deconstantize => 'V1'
# searches for serializers in the V1:: namespace with the name UserSerializer

# used
class V1::UserSerializer
  ...
end

# not used since V1::UserSerializer resolved first
class UserSerializer
  ...
end
```

3. Version inferred

```
class UsersApi < Grape::Api
  version 'v2'

  resource :users do
    get '/:id' do
      current_user
    end
  end
end
# 'v2'.classify => V2
# searches for serializers in the V2:: namespace with the name UserSerializer

# used
class V2::UserSerializer
  ...
end

# not used since V2::UserSerializer resolved first
class UserSerializer
  ...
end
```

4. Default ASM lookup

```
class V1::UsersApi < Grape::Api
  version 'v2'

  resource :users do
    get '/:id' do
      current_user
    end
  end
end
# searches for serializers in the V1:: namespace, none found
# searches for serializers in the V2:: namespace, none found

# used as no other serializers were found
class UserSerializer
  ...
end
```

#### Collection Serializer Resolution

Serializer resolution for collections also uses the above strategy, but has
the added option of overriding the member serializer if the `each_serializer`
options is specified.

```
class UsersApi < Grape::Api
  resource :users do
    get each_serializer: SpecifiedUserSerializer do
      User.all
    end
  end
end
```


### Upgrading to v1.4.0

#### Changes in Serializer Namespacing

Version 1.4.0 introduced changes in serializer namespacing when using Grape
API versioning.

If you haven't declared an API version in Grape, nothing changed.

If your Grape API is versioned, which means you have declared at least one
version in Grape, you must namespace your serializers accordingly.

For example, given the following API.

```ruby
module CandyBar
  class Core < Grape::API
    version 'candy_bar', using: :header, vendor: 'acme'
  end
end

module Chocolate
  class Core < Grape::API
    version 'chocolate', using: :header, vendor: 'acme'
  end
end

class API < Grape::API
  format :json
  formatter :json, Grape::Formatter::ActiveModelSerializers

  mount CandyBar::Core
  mount Chocolate::Core
end
```

Namespace serializers according to each version.

```ruby
module CandyBar
  class UserSerializer < ActiveModel::Serializer
    attributes :first_name, :last_name, :email
  end
end

module Chocolate
  class UserSerializer < ActiveModel::Serializer
    attributes :first_name, :last_name
  end
end
```

This will allow you to keep your serializers easier to maintain and more
organized.

```
app
└── api
    ├── chocolate
        └── core.rb
    └── candy_bar
        └── core.rb
    api.rb
└── serializers
    ├── chocolate
        └── user_serializer.rb
    └── candy_bar
        └── user_serializer.rb
```

or alternatively:

```
└── serializers
    ├── chocolate_user_serializer.rb
    └── candy_bar_user_serializer.rb
```

Thus, ActiveModelSerializer will fetch automatically the right serializer to
render.

### Upgrading to v1.0.0

#### Changes to Array Roots

When serializing an array, the array root is set to the innermost namespace
name if there is one, otherwise it is set to the route name.

In the following example the array root is `users`.

```ruby
namespace :users do
  get ":id" do
    @user = User.find(params[:id])
  end
end
```

In the following example the array root is `people`.

```ruby
get "people" do
  @user = User.all
end
```