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
| OPTIONS | = | [ :rewrite, :as, :if, :unless, :using, :with, :proc, :documentation, :format_with, :safe, :attr_path, :if_extras, :unless_extras, :merge | All supported options. |
| delegator | [R] | |
| formatters | [W] | |
| object | [R] | |
| options | [R] | |
| root_exposure | [W] |
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.
This method is the primary means by which you will declare what attributes should be exposed by the entity.
@option options :as Declare an alias for the representation of this attribute. @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
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
Returns all formatters that are registered for this and it‘s ancestors @return [Hash] of formatters
Merges the given options with current block options.
@param options [Hash] Exposure options.
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
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
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
Returns exposures that have been declared for this Entity on the top level. @return [Array] of exposures
Raises an error if the given options include unknown keys. Renames aliased options.
@param options [Hash] Exposure options.
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
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.