- Grape::ActiveModelSerializers
- Installation
- Dependencies
- Usage
- Require grape-active_model_serializers
- Tell your API to use Grape::Formatter::ActiveModelSerializers
- Writing Serializers
- Serializers are inferred by active_record model names
- Array Roots
- API Versioning
- Manually specifying serializer / adapter options
- Custom Metadata
- Default Serializer Options
- Current User
- Full Example
- Contributing
- History
Use active_model_serializers with Grape!
Add the grape and grape-active_model_serializers gems to Gemfile and run bundle install.
gem 'grape-active_model_serializers'See UPGRADING if you're upgrading from a previous version.
- >= Ruby v3.1
- >= grape v2.3.0
- >= active_model_serializers v0.10.0
# config.ru require 'grape-active_model_serializers'class API < Grape::API format :json formatter :json, Grape::Formatter::ActiveModelSerializers # Serializes errors with ActiveModel::Serializer::ErrorSerializer if an ActiveModel. # Serializer conforms to the adapter, ex: json, jsonapi. # So an error formatted with a jsonapi formatter would render as per: # http://jsonapi.org/format/#error-objects error_formatter :json, Grape::Formatter::ActiveModelSerializers endgrape-active_model_serializers will search for serializers for the objects returned by your grape API.
namespace :users do get ":id" do @user = User.find(params[:id]) end endIn this case, as User objects are being returned, grape-active_model_serializers will look for a serializer named UserSerializer.
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 API the array root is users.
namespace :users do get ":id" do @user = User.find(params[:id]) end endIn the following example the array root is people.
get "people" do @user = User.all endIf your Grape API is versioned 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 endNamespace your 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 endThis keeps serializers organized.
app └── api ├── chocolate └── core.rb └── candy_bar └── core.rb api.rb └── serializers ├── chocolate └── user_serializer.rb └── candy_bar └── user_serializer.rb Or as follows.
└── serializers ├── chocolate_user_serializer.rb └── candy_bar_user_serializer.rb ActiveModelSerializer will fetch automatically the right serializer to render.
# Serializer and adapter options can be specified on routes or namespaces. namespace 'foo', serializer: BarSerializer do get "/" do # will use "bar" serializer end # Options specified on a route or namespace override those of the containing namespace. get "/home", serializer: HomeSerializer do # will use "home" serializer end # All standard options for `ActiveModel::Serializers` are supported. get "/fancy_homes", root: 'world', each_serializer: FancyHomesSerializer ... end end# Serializer and adapter options can also be specified in the body of the route resource :users do get '/:id' do if conditional # uses UserSerializer and configured default adapter automatically current_user else # uses specified serializer and adapter render current_user, serializer: ErrorSerializer, adapter: :attributes end end end# Adhoc serializer options can be specified in the body of the route resource :users do get '/:id' do render current_user, extra: { adhoc_name_option: 'value' } end end class UserSerializer def name instance_options[:adhoc_name_option] # accessible in instance_options end end# Control any additional metadata using meta and meta_key get "/homes" collection = Home.all render collection, { meta: { page: 5, current_page: 3 }, meta_key: :pagination_info } endhelpers do def default_serializer_options { only: params[:only], except: params[:except] } end endOne of the nice features of ActiveModel::Serializers is that it provides access to the authorization context via the current_user.
In Grape, you can get the same behavior by defining a current_user helper method.
helpers do def current_user @current_user ||= User.where(access_token: params[:token]).first end def authenticate! error!('401 Unauthenticated', 401) unless current_user end endThen, in your serializer, you could show or hide some elements based on the current user's permissions.
class PostSerializer < ActiveModel::Serializer def include_admin_comments? current_user.roles.member? :admin end endNote: in the 0.9.x stable version of active model serializers, you have to access current user on scope - so scope.current_user.
class User < ActiveRecord::Base attr_accessor :first_name, :last_name, :password, :email end class UserSerializer < ActiveModel::Serializer attributes :first_name, :last_name end class API < Grape::API get("/home") do User.new({first_name: 'JR', last_name: 'HE', email: 'contact@jrhe.co.uk'}) end end API.new.get "/home" # => '{ user: { first_name: "JR", last_name: "HE" } }'See CONTRIBUTING.
Structured and based upon grape-rabl.
