Class: Grape::Entity

Inherits:
Object
  • Object
show all
Defined in:
lib/grape_entity/entity.rb

Overview

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.

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:

Examples:

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

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

Defined Under Namespace

Modules: DSL

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(object, options = {}) ⇒ Entity

Returns a new instance of Entity.



340
341
342
 
# File 'lib/grape_entity/entity.rb', line 340

def initialize(object, options = {})
  @object, @options = object, options
end

Class Attribute Details

._nested_exposures_hash ⇒ Object

Returns the value of attribute _nested_exposures_hash.



188
189
190
 
# File 'lib/grape_entity/entity.rb', line 188

def _nested_exposures_hash
  @_nested_exposures_hash
end

Instance Attribute Details

#object ⇒ Object (readonly)

Returns the value of attribute object.



45
46
47
 
# File 'lib/grape_entity/entity.rb', line 45

def object
  @object
end

#options ⇒ Object (readonly)

Returns the value of attribute options.



45
46
47
 
# File 'lib/grape_entity/entity.rb', line 45

def options
  @options
end

Class Method Details

.documentation ⇒ Object

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.



208
209
210
211
212
213
214
215
216
217
218
219
220
221
 
# File 'lib/grape_entity/entity.rb', line 208

def self.documentation
  @documentation ||= exposures.inject({}) do |memo, (attribute, exposure_options)|
    unless exposure_options[:documentation].nil? || exposure_options[:documentation].empty?
      memo[key_for(attribute)] = exposure_options[:documentation]
    end
    memo
  end

  if superclass.respond_to? :documentation
    @documentation = superclass.documentation.merge(@documentation)
  end

  @documentation
end

.expose(*args, &block) ⇒ Object

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

Parameters:

  • options (Hash) —

    a customizable set of options

Raises:

  • (ArgumentError) 


126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/grape_entity/entity.rb', line 126

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 block-setting on multi-attribute exposures." if block_given?
  end

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

  options[:proc] = block if block_given? && block.parameters.any?

  @nested_attributes ||= []

  args.each do |attribute|
    unless @nested_attributes.empty?
      attribute = "#{@nested_attributes.last}__#{attribute}"
      options[:nested] = true
      nested_exposures_hash[@nested_attributes.last.to_sym] ||= {}
      nested_exposures_hash[@nested_attributes.last.to_sym][attribute.to_sym] = options
    end

    exposures[attribute.to_sym] = options

    # Nested exposures are given in a block with no parameters.
    if block_given? && block.parameters.empty?
      @nested_attributes << attribute
      block.call
      @nested_attributes.pop
    end
  end
end

.exposures ⇒ Object

Returns a hash of exposures that have been declared for this Entity or ancestors. The keys are symbolized references to methods on the containing object, the values are the options that were passed into expose.



177
178
179
180
181
182
183
184
185
 
# File 'lib/grape_entity/entity.rb', line 177

def self.exposures
  @exposures ||= {}

  if superclass.respond_to? :exposures
    @exposures = superclass.exposures.merge(@exposures)
  end

  @exposures
end

.format_with(name, &block) ⇒ Object

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.

Examples:

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

Formatters are available to all decendants


Grape::Entity.format_with :timestamp do |date|
  date.strftime('%m/%d/%Y')
end

Parameters:

  • name (Symbol) —

    the name of the formatter

  • block (Proc) —

    the block that will interpret the exposed attribute

Raises:

  • (ArgumentError) 


249
250
251
252
 
# File 'lib/grape_entity/entity.rb', line 249

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 ⇒ Object

Returns a hash of all formatters that are registered for this and it's ancestors.



255
256
257
258
259
260
261
262
263
 
# File 'lib/grape_entity/entity.rb', line 255

def self.formatters
  @formatters ||= {}

  if superclass.respond_to? :formatters
    @formatters = superclass.formatters.merge(@formatters)
  end

  @formatters
end

.nested_exposures ⇒ Object 



194
195
196
197
198
199
200
201
202
 
# File 'lib/grape_entity/entity.rb', line 194

def nested_exposures
  value = nested_exposures_hash

  if superclass.respond_to? :nested_exposures
    value = superclass.nested_exposures.deep_merge(value)
  end

  value
end

.nested_exposures_hash ⇒ Object 



190
191
192
 
# File 'lib/grape_entity/entity.rb', line 190

def nested_exposures_hash
  self._nested_exposures_hash ||= {}
end

.represent(objects, options = {}) ⇒ Object

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.

Parameters:

  • objects (Object or Array) —

    One or more objects to be represented.

  • options (Hash) (defaults to: {}) —

    Options that will be passed through to each entity representation.

Options Hash (options):

  • :root (String) —

    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.



322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
 
# File 'lib/grape_entity/entity.rb', line 322

def self.represent(objects, options = {})
  if objects.respond_to?(:to_ary)
    inner = objects.to_ary.map { |object| new(object, { collection: true }.merge(options)) }
    inner = inner.map(&:serializable_hash) if options[:serializable]
  else
    inner = new(objects, options)
    inner = inner.serializable_hash if options[:serializable]
  end

  root_element = if options.has_key?(:root)
                   options[:root]
                 else
                   objects.respond_to?(:to_ary) ? @collection_root : @root
                 end

  root_element ? { root_element => inner } : inner
end

.root(plural, singular = nil) ⇒ Object

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

Examples:

Entity Definition


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

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

Parameters:

  • 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.

  • singular (String) (defaults to: nil) —

    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.



304
305
306
307
 
# File 'lib/grape_entity/entity.rb', line 304

def self.root(plural, singular = nil)
  @collection_root = plural
  @root = singular
end

.with_options(options) ⇒ Object

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

Examples:

Multi-exposure if


class MyEntity < Grape::Entity
  with_options if: { awesome: true } do
    expose :awesome, :sweet
  end
end


168
169
170
171
172
 
# File 'lib/grape_entity/entity.rb', line 168

def self.with_options(options)
  (@block_options ||= []).push(valid_options(options))
  yield
  @block_options.pop
end

Instance Method Details

#documentation ⇒ Object 



354
355
356
 
# File 'lib/grape_entity/entity.rb', line 354

def documentation
  self.class.documentation
end

#exposures ⇒ Object 



344
345
346
 
# File 'lib/grape_entity/entity.rb', line 344

def exposures
  self.class.exposures
end

#formatters ⇒ Object 



358
359
360
 
# File 'lib/grape_entity/entity.rb', line 358

def formatters
  self.class.formatters
end

#serializable_hash(runtime_options = {}) ⇒ Object Also known as: as_json

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.

Parameters:

  • runtime_options (Hash) (defaults to: {}) —

    Any options you pass in here will be known to the entity representation, this is where you can trigger things from conditional options etc.



369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
 
# File 'lib/grape_entity/entity.rb', line 369

def serializable_hash(runtime_options = {})
  return nil if object.nil?
  opts = options.merge(runtime_options || {})
  valid_exposures.inject({}) do |output, (attribute, exposure_options)|
    if conditions_met?(exposure_options, opts)
      partial_output = value_for(attribute, opts)
      output[self.class.key_for(attribute)] =
        if partial_output.respond_to? :serializable_hash
          partial_output.serializable_hash(runtime_options)
        elsif partial_output.kind_of?(Array) && !partial_output.map { |o| o.respond_to? :serializable_hash }.include?(false)
          partial_output.map { |o| o.serializable_hash }
        elsif partial_output.kind_of?(Hash)
          partial_output.each do |key, value|
            partial_output[key] = value.serializable_hash if value.respond_to? :serializable_hash
          end
        else
          partial_output
        end
    end
    output
  end
end

#to_json(options = {}) ⇒ Object 



394
395
396
397
 
# File 'lib/grape_entity/entity.rb', line 394

def to_json(options = {})
  options = options.to_h if options && options.respond_to?(:to_h)
  MultiJson.dump(serializable_hash(options))
end

#to_xml(options = {}) ⇒ Object 



399
400
401
402
 
# File 'lib/grape_entity/entity.rb', line 399

def to_xml(options = {})
  options = options.to_h if options && options.respond_to?(:to_h)
  serializable_hash(options).to_xml(options)
end

#valid_exposures ⇒ Object 



348
349
350
351
352
 
# File 'lib/grape_entity/entity.rb', line 348

def valid_exposures
  exposures.reject { |a, options| options[:nested] }.select do |attribute, exposure_options|
    valid_exposure?(attribute, exposure_options)
  end
end