grape-active_model_serializers/UPGRADING.md

Upgrading to v.1.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.

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.

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.

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

In the following example the array root is people.

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