class Grape::Entity

An Entity is a lightweight structure that allows you to easily represent data from your application in a consistent and abstracted way in your API. Entities can also provide documentation for the fields exposed.

@example Entity Definition

module API
  module Entities
    class User < Grape::Entity
      expose :first_name, :last_name, :screen_name, :location
      expose :field, documentation: { type: "string", desc: "describe the field" }
      expose :latest_status, using: API::Status, as: :status, unless: { collection: true }
      expose :email, if: { type: :full }
      expose :new_attribute, if: { version: 'v2' }
      expose(:name) { |model, options| [model.first_name, model.last_name].join(' ') }
    end
  end
end

Entities are not independent structures, rather, they create representations of other Ruby objects using a number of methods that are convenient for use in an API. Once you've defined an Entity, you can use it in your API like this:

@example Usage in the API Layer

module API
  class Users < Grape::API
    version 'v2'

    desc 'User index', { params: API::Entities::User.documentation }
    get '/users' do
      @users = User.all
      type = current_user.admin? ? :full : :default
      present @users, with: API::Entities::User, type: type
    end
  end
end

Constants

OPTIONS

All supported options.

Attributes

formatters[W]
root_exposure[W]
delegator[R]
object[R]
options[R]

Public Class Methods

build_exposure_for_attribute(attribute, nesting_stack, options, block) click to toggle source

rubocop:enable Layout/LineLength

# File lib/grape_entity/entity.rb, line 219
def self.build_exposure_for_attribute(attribute, nesting_stack, options, block)
  exposure_list = nesting_stack.empty? ? root_exposures : nesting_stack.last.nested_exposures

  exposure = Exposure.new(attribute, options)

  exposure_list.delete_by(attribute) if exposure.override?

  exposure_list << exposure

  # Nested exposures are given in a block with no parameters.
  return unless exposure.nesting?

  nesting_stack << exposure
  block.call
  nesting_stack.pop
end
can_unexpose?() click to toggle source
# File lib/grape_entity/entity.rb, line 258
def self.can_unexpose?
  (@nesting_stack ||= []).empty?
end
cannot_unexpose!() click to toggle source
# File lib/grape_entity/entity.rb, line 262
def self.cannot_unexpose!
  raise "You cannot call 'unexpose` inside of nesting exposure!"
end
delegation_opts() click to toggle source
# File lib/grape_entity/entity.rb, line 130
def delegation_opts
  @delegation_opts ||= { hash_access: hash_access }
end
documentation() click to toggle source

Returns a hash, the keys are symbolized references to fields in the entity, the values are document keys in the entity's documentation key. When calling docmentation, any exposure without a documentation key will be ignored.

# File lib/grape_entity/entity.rb, line 284
def self.documentation
  @documentation ||= root_exposures.each_with_object({}) do |exposure, memo|
    memo[exposure.key] = exposure.documentation if exposure.documentation && !exposure.documentation.empty?
  end
end
expose(*args, &block) click to toggle source

This method is the primary means by which you will declare what attributes should be exposed by the entity.

@option options :expose_nil When set to false the associated exposure will not

be rendered if its value is nil.

@option options :as Declare an alias for the representation of this attribute.

If a proc is presented it is evaluated in the context of the entity so object
and the entity methods are available to it.

@example as: a proc or lambda

object = OpenStruct(awesomeness: 'awesome_key', awesome: 'not-my-key', other: 'other-key' )

class MyEntity < Grape::Entity
  expose :awesome, as: proc { object.awesomeness }
  expose :awesomeness, as: ->(object, opts) { object.other }
end

=> { 'awesome_key': 'not-my-key', 'other-key': 'awesome_key' }

Note the parameters passed in via the lambda syntax.

@option options :if When passed a Hash, the attribute will only be exposed if the

runtime options match all the conditions passed in. When passed a lambda, the
lambda will execute with two arguments: the object being represented and the
options passed into the representation call. Return true if you want the attribute
to be exposed.

@option options :unless When passed a Hash, the attribute will be exposed if the

runtime options fail to match any of the conditions passed in. If passed a lambda,
it will yield the object being represented and the options passed to the
representation call. Return true to prevent exposure, false to allow it.

@option options :using This option allows you to map an attribute to another Grape

Entity. Pass it a Grape::Entity class and the attribute in question will
automatically be transformed into a representation that will receive the same
options as the parent entity when called. Note that arrays are fine here and
will automatically be detected and handled appropriately.

@option options :proc If you pass a Proc into this option, it will

be used directly to determine the value for that attribute. It
will be called with the represented object as well as the
runtime options that were passed in. You can also just supply a
block to the expose call to achieve the same effect.

@option options :documentation Define documenation for an exposed

field, typically the value is a hash with two fields, type and desc.

@option options :merge This option allows you to merge an exposed field to the root

rubocop:disable Layout/LineLength

# File lib/grape_entity/entity.rb, line 191
def self.expose(*args, &block)
  options = merge_options(args.last.is_a?(Hash) ? args.pop : {})

  if args.size > 1

    raise ArgumentError, 'You may not use the :as option on multi-attribute exposures.' if options[:as]
    raise ArgumentError, 'You may not use the :expose_nil on multi-attribute exposures.' if options.key?(:expose_nil)
    raise ArgumentError, 'You may not use block-setting on multi-attribute exposures.' if block_given?
  end

  if block_given?
    if options[:format_with].respond_to?(:call)
      raise ArgumentError, 'You may not use block-setting when also using format_with'
    end

    if block.parameters.any?
      options[:proc] = block
    else
      options[:nesting] = true
    end
  end

  @documentation = nil
  @nesting_stack ||= []
  args.each { |attribute| build_exposure_for_attribute(attribute, @nesting_stack, options, block) }
end
find_exposure(attribute) click to toggle source
# File lib/grape_entity/entity.rb, line 242
def self.find_exposure(attribute)
  root_exposures.find_by(attribute)
end
format_with(name, &block) click to toggle source

This allows you to declare a Proc in which exposures can be formatted with. It take a block with an arity of 1 which is passed as the value of the exposed attribute.

@param name [Symbol] the name of the formatter @param block [Proc] the block that will interpret the exposed attribute

@example Formatter declaration

module API
  module Entities
    class User < Grape::Entity
      format_with :timestamp do |date|
        date.strftime('%m/%d/%Y')
      end

      expose :birthday, :last_signed_in, format_with: :timestamp
    end
  end
end

@example Formatters are available to all decendants

Grape::Entity.format_with :timestamp do |date|
  date.strftime('%m/%d/%Y')
end
# File lib/grape_entity/entity.rb, line 316
def self.format_with(name, &block)
  raise ArgumentError, 'You must pass a block for formatters' unless block_given?

  formatters[name.to_sym] = block
end
formatters() click to toggle source

Returns all formatters that are registered for this and it's ancestors @return [Hash] of formatters

# File lib/grape_entity/entity.rb, line 112
def formatters
  @formatters ||= {}
end
hash_access() click to toggle source
# File lib/grape_entity/entity.rb, line 116
def hash_access
  @hash_access ||= :to_sym
end
hash_access=(value) click to toggle source
# File lib/grape_entity/entity.rb, line 120
def hash_access=(value)
  @hash_access =
    case value
    when :to_s, :str, :string
      :to_s
    else
      :to_sym
    end
end
inherited(subclass) click to toggle source
Calls superclass method
# File lib/grape_entity/entity.rb, line 137
def self.inherited(subclass)
  subclass.root_exposure = root_exposure.dup
  subclass.formatters = formatters.dup

  super
end
merge_options(options) click to toggle source

Merges the given options with current block options.

@param options [Hash] Exposure options.

# File lib/grape_entity/entity.rb, line 591
def self.merge_options(options)
  opts = {}

  merge_logic = proc do |key, existing_val, new_val|
    if %i[if unless].include?(key)
      if existing_val.is_a?(Hash) && new_val.is_a?(Hash)
        existing_val.merge(new_val)
      elsif new_val.is_a?(Hash)
        (opts["#{key}_extras".to_sym] ||= []) << existing_val
        new_val
      else
        (opts["#{key}_extras".to_sym] ||= []) << new_val
        existing_val
      end
    else
      new_val
    end
  end

  @block_options ||= []
  opts.merge @block_options.inject({}) { |final, step|
    final.merge(step, &merge_logic)
  }.merge(valid_options(options), &merge_logic)
end
new(object, options = {}) click to toggle source
# File lib/grape_entity/entity.rb, line 480
def initialize(object, options = {})
  @object = object
  @options = options.is_a?(Options) ? options : Options.new(options)
  @delegator = Delegator.new(object)
end
present_collection(present_collection = false, collection_name = :items) click to toggle source

This allows you to present a collection of objects.

@param present_collection [true or false] when true all objects will be available as

 items in your presenter instead of wrapping each object in an instance of your presenter.
When false (default) every object in a collection to present will be wrapped separately
into an instance of your presenter.

@param collection_name [Symbol] the name of the collection accessor in your entity object.

Default :items

@example Entity Definition

module API
  module Entities
    class User < Grape::Entity
      expose :id
    end

    class Users < Grape::Entity
      present_collection true
      expose :items, as: 'users', using: API::Entities::User
      expose :version, documentation: { type: 'string',
                                        desc: 'actual api version',
                                        required: true }

      def version
        options[:version]
      end
    end
  end
end

@example Usage in the API Layer

module API
  class Users < Grape::API
    version 'v2'

    # this will render { "users" : [ { "id" : "1" }, { "id" : "2" } ], "version" : "v2" }
    get '/users' do
      @users = User.all
      present @users, with: API::Entities::Users
    end

    # this will render { "user" : { "id" : "1" } }
    get '/users/:id' do
      @user = User.find(params[:id])
      present @user, with: API::Entities::User
    end
  end
end
# File lib/grape_entity/entity.rb, line 417
def self.present_collection(present_collection = false, collection_name = :items)
  @present_collection = present_collection
  @collection_name = collection_name
end
represent(objects, options = {}) click to toggle source

This convenience method allows you to instantiate one or more entities by passing either a singular or collection of objects. Each object will be initialized with the same options. If an array of objects is passed in, an array of entities will be returned. If a single object is passed in, a single entity will be returned.

@param objects [Object or Array] One or more objects to be represented. @param options [Hash] Options that will be passed through to each entity

representation.

@option options :root [String or false] override the default root name set for the entity.

Pass nil or false to represent the object or objects with no root name
even if one is defined for the entity.

@option options :serializable [true or false] when true a serializable Hash will be returned

@option options :only [Array] all the fields that should be returned @option options :except [Array] all the fields that should not be returned

# File lib/grape_entity/entity.rb, line 439
def self.represent(objects, options = {})
  @present_collection ||= nil
  if objects.respond_to?(:to_ary) && !@present_collection
    root_element = root_element(:collection_root)
    inner = objects.to_ary.map { |object| new(object, options.reverse_merge(collection: true)).presented }
  else
    objects = { @collection_name => objects } if @present_collection
    root_element = root_element(:root)
    inner = new(objects, options).presented
  end

  root_element = options[:root] if options.key?(:root)

  root_element ? { root_element => inner } : inner
end
root(plural, singular = nil) click to toggle source

This allows you to set a root element name for your representation.

@param plural [String] the root key to use when representing

a collection of objects. If missing or nil, no root key will be used
when representing collections of objects.

@param singular [String] the root key to use when representing

a single object. If missing or nil, no root key will be used when
representing an individual object.

@example Entity Definition

module API
  module Entities
    class User < Grape::Entity
      root 'users', 'user'
      expose :id
    end
  end
end

@example Usage in the API Layer

module API
  class Users < Grape::API
    version 'v2'

    # this will render { "users" : [ { "id" : "1" }, { "id" : "2" } ] }
    get '/users' do
      @users = User.all
      present @users, with: API::Entities::User
    end

    # this will render { "user" : { "id" : "1" } }
    get '/users/:id' do
      @user = User.find(params[:id])
      present @user, with: API::Entities::User
    end
  end
end
# File lib/grape_entity/entity.rb, line 361
def self.root(plural, singular = nil)
  @collection_root = plural
  @root = singular
end
root_element(root_type) click to toggle source

This method returns the entity's root or collection root node, or its parent's @param root_type: either :collection_root or just :root

# File lib/grape_entity/entity.rb, line 457
def self.root_element(root_type)
  instance_variable = "@#{root_type}"
  if instance_variable_defined?(instance_variable) && instance_variable_get(instance_variable)
    instance_variable_get(instance_variable)
  elsif superclass.respond_to? :root_element
    superclass.root_element(root_type)
  end
end
root_exposure() click to toggle source
# File lib/grape_entity/entity.rb, line 104
def root_exposure
  @root_exposure ||= Exposure.new(nil, nesting: true)
end
root_exposures() click to toggle source

Returns exposures that have been declared for this Entity on the top level. @return [Array] of exposures

# File lib/grape_entity/entity.rb, line 238
def self.root_exposures
  root_exposure.nested_exposures
end
unexpose(*attributes) click to toggle source
# File lib/grape_entity/entity.rb, line 246
def self.unexpose(*attributes)
  cannot_unexpose! unless can_unexpose?
  @documentation = nil
  root_exposures.delete_by(*attributes)
end
unexpose_all() click to toggle source
# File lib/grape_entity/entity.rb, line 252
def self.unexpose_all
  cannot_unexpose! unless can_unexpose?
  @documentation = nil
  root_exposures.clear
end
valid_options(options) click to toggle source

Raises an error if the given options include unknown keys. Renames aliased options.

@param options [Hash] Exposure options.

# File lib/grape_entity/entity.rb, line 620
def self.valid_options(options)
  options.each_key do |key|
    raise ArgumentError, "#{key.inspect} is not a valid option." unless OPTIONS.include?(key)
  end

  options[:using] = options.delete(:with) if options.key?(:with)
  options
end
with_options(options) { || ... } click to toggle source

Set options that will be applied to any exposures declared inside the block.

@example Multi-exposure if

class MyEntity < Grape::Entity
  with_options if: { awesome: true } do
    expose :awesome, :sweet
  end
end
# File lib/grape_entity/entity.rb, line 275
def self.with_options(options)
  (@block_options ||= []).push(valid_options(options))
  yield
  @block_options.pop
end

Public Instance Methods

as_json(runtime_options = {})
Alias for: serializable_hash
delegate_attribute(attribute) click to toggle source
# File lib/grape_entity/entity.rb, line 538
def delegate_attribute(attribute)
  if is_defined_in_entity?(attribute)
    send(attribute)
  elsif delegator.accepts_options?
    delegator.delegate(attribute, **self.class.delegation_opts)
  else
    delegator.delegate(attribute)
  end
end
documentation() click to toggle source
# File lib/grape_entity/entity.rb, line 494
def documentation
  self.class.documentation
end
exec_with_attribute(attribute, &block) click to toggle source
# File lib/grape_entity/entity.rb, line 530
def exec_with_attribute(attribute, &block)
  instance_exec(delegate_attribute(attribute), &block)
end
exec_with_object(options, &block) click to toggle source
# File lib/grape_entity/entity.rb, line 517
def exec_with_object(options, &block)
  if block.parameters.count == 1
    instance_exec(object, &block)
  else
    instance_exec(object, options, &block)
  end
rescue StandardError => e
  # it handles: https://github.com/ruby/ruby/blob/v3_0_0_preview1/NEWS.md#language-changes point 3, Proc
  raise Grape::Entity::Deprecated.new e.message, 'in ruby 3.0' if e.is_a?(ArgumentError)

  raise e
end
formatters() click to toggle source
# File lib/grape_entity/entity.rb, line 498
def formatters
  self.class.formatters
end
inspect() click to toggle source

Prevent default serialization of :options or :delegator.

# File lib/grape_entity/entity.rb, line 475
def inspect
  fields = serializable_hash.map { |k, v| "#{k}=#{v}" }
  "#<#{self.class.name}:#{object_id} #{fields.join(' ')}>"
end
is_defined_in_entity?(attribute) click to toggle source
# File lib/grape_entity/entity.rb, line 548
def is_defined_in_entity?(attribute)
  return false unless respond_to?(attribute, true)

  ancestors = self.class.ancestors
  ancestors.index(Grape::Entity) > ancestors.index(method(attribute).owner)
end
presented() click to toggle source
# File lib/grape_entity/entity.rb, line 466
def presented
  if options[:serializable]
    serializable_hash
  else
    self
  end
end
root_exposure() click to toggle source
# File lib/grape_entity/entity.rb, line 490
def root_exposure
  self.class.root_exposure
end
root_exposures() click to toggle source
# File lib/grape_entity/entity.rb, line 486
def root_exposures
  self.class.root_exposures
end
serializable_hash(runtime_options = {}) click to toggle source

The serializable hash is the Entity's primary output. It is the transformed hash for the given data model and is used as the basis for serialization to JSON and other formats.

@param runtime_options [Hash] Any options you pass in here will be known to the entity

representation, this is where you can trigger things from conditional options
etc.
# File lib/grape_entity/entity.rb, line 509
def serializable_hash(runtime_options = {})
  return nil if object.nil?

  opts = options.merge(runtime_options || {})

  root_exposure.serializable_value(self, opts)
end
Also aliased as: as_json
to_json(options = {}) click to toggle source
# File lib/grape_entity/entity.rb, line 557
def to_json(options = {})
  options = options.to_h if options&.respond_to?(:to_h)
  MultiJson.dump(serializable_hash(options))
end
to_xml(options = {}) click to toggle source
# File lib/grape_entity/entity.rb, line 562
def to_xml(options = {})
  options = options.to_h if options&.respond_to?(:to_h)
  serializable_hash(options).to_xml(options)
end
value_for(key, options = Options.new) click to toggle source
# File lib/grape_entity/entity.rb, line 534
def value_for(key, options = Options.new)
  root_exposure.valid_value_for(key, self, options)
end