GrapeEntity
CI
Introduction
This gem is the Entity extracted out of Grape.
Grape's Entity is a great idea: a API focussed Facade that sits on top of a model object.
The intend is to allow the Entity to be used outside of Grape and provide additional exposure to parts of the entity needed to simplify testing parts of an API.
We intend to use the specs from grape to ensure we maintain compatability with Grape through our changes so that we can use the Entity to replace Grape's internal Entity.
Goals
Through my own use of Entities I have found them really useful but wished they could be reused in other situations. In the context of Grape I wish it was easier to test the Entity so that you could test them seperately from your API and isolate their behavior. Entities also have a deep connection with the model and they should know what parameters are required and (especially in the case of an ActiveRecord Model) they should know how to ask about validation.
The Entity is a simple Facade on top of the model to transform it into the object you want to expose on your API.
There is probably something heavier than an Entity that exists as well. A way to get a model object back from the Entity.
In this spirit I want to give Entities a life of their own.
Project Tracking
- - Need to setup something up for this -
Reusable Responses with Entities
Entities are a reusable means for converting Ruby objects to API responses. Entities can be used to conditionally include fields, nest other entities, and build ever larger responses, using inheritance.
Defining Entities
Entities inherit from GrapeEntity::Entity, and define a simple DSL. Exposures can use
runtime options to determine which fields should be visible, these options are
available to :if
, :unless
, and :proc
. The option keys :version
and :collection
will always be defined. The :version
key is defined as api.version
. The
:collection
key is boolean, and defined as true
if the object presented is an
array.
expose SYMBOLS
- define a list of fields which will always be exposed
expose SYMBOLS, HASH
- HASH keys include
:if
,:unless
,:proc
,:as
,:using
,:format_with
,:documentation
:if
and:unless
accept hashes (passed during runtime) or procs (arguments are object and options)
- HASH keys include
expose SYMBOL, { :format_with => :formatter }
- expose a value, formatting it first
:format_with
can only be applied to one exposure at a time
expose SYMBOL, { :as => "alias" }
- Expose a value, changing its hash key from SYMBOL to alias
:as
can only be applied to one exposure at a time
expose SYMBOL BLOCK
- block arguments are object and options
- expose the value returned by the block
- block can only be applied to one exposure at a time
module API
module Entities
class Status < GrapeEntity::Entity
expose :user_name
expose :text, :documentation => { :type => "string", :desc => "Status update text." }
expose :ip, :if => { :type => :full }
expose :user_type, user_id, :if => lambda{ |status, options| status.user.public? }
expose :digest { |status, options| Digest::MD5.hexdigest(satus.txt) }
expose :replies, :using => API::Status, :as => :replies
end
end
end
module API
module Entities
class StatusDetailed < API::Entities::Status
expose :internal_id
end
end
end
Using the Exposure DSL
Grape ships with a DSL to easily define entities within the context of an existing class:
class Status
include GrapeEntity::Entity::DSL
entity :text, :user_id do
expose :detailed, if: :conditional
end
end
The above will automatically create a Status::Entity
class and define properties on it according
to the same rules as above. If you only want to define simple exposures you don't have to supply
a block and can instead simply supply a list of comma-separated symbols.
Using Entities
Once an entity is defined, it can be used within endpoints, by calling present
. The present
method accepts two arguments, the object to be presented and the options associated with it. The
options hash must always include :with
, which defines the entity to expose.
If the entity includes documentation it can be included in an endpoint's description.
module API
class Statuses < GrapeEntity::API
version 'v1'
desc 'Statuses index', {
:object_fields => API::Entities::Status.documentation
}
get '/statuses' do
statuses = Status.all
type = current_user.admin? ? :full : :default
present statuses, with: API::Entities::Status, :type => type
end
end
end
Entity Organization
In addition to separately organizing entities, it may be useful to put them as namespaced classes underneath the model they represent.
class Status
def entity
Status.new(self)
end
class Entity < GrapeEntity::Entity
expose :text, :user_id
end
end
If you organize your entities this way, Grape will automatically detect the Entity
class and
use it to present your models. In this example, if you added present User.new
to your endpoint,
Grape would automatically detect that there is a Status::Entity
class and use that as the
representative entity. This can still be overridden by using the :with
option or an explicit
represents
call.
Caveats
Entities with duplicate exposure names and conditions will silently overwrite one another.
In the following example, when object.check
equals "foo", only field_a
will be exposed.
However, when object.check
equals "bar" both field_b
and foo
will be exposed.
module API
module Entities
class Status < GrapeEntity::Entity
expose :field_a, :foo, :if => lambda { |object, | object.check == "foo" }
expose :field_b, :foo, :if => lambda { |object, | object.check == "bar" }
end
end
end
This can be problematic, when you have mixed collections. Using respond_to?
is safer.
module API
module Entities
class Status < GrapeEntity::Entity
expose :field_a, :if => lambda { |object, | object.check == "foo" }
expose :field_b, :if => lambda { |object, | object.check == "bar" }
expose :foo, :if => lambda { |object, | object.respond_to?(:foo) }
end
end
end
Installation
Add this line to your application's Gemfile:
gem 'grape-entity'
And then execute:
$ bundle
Or install it yourself as:
$ gem install grape-entity
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
License
MIT License. See LICENSE for details.
Copyright
Copyright (c) 2010-2012 Michael Bleigh, and Intridea, Inc.