root element name support for entities

You can specify root 'thing', 'things' in your Entity class,
and your object or objects will be represented wrapped in a
hash, with the appropriate top-level key.

Author: Jon Evans

lib/grape/entity.rb

@@ -1,7 +1,7 @@
 require 'hashie'
 
 module Grape
-  # An Entity is a lightweight structure that allows you to easily 
+  # 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.
   #
@@ -19,7 +19,7 @@ module Grape
   #     end
   #   end
   #
-  # Entities are not independent structures, rather, they create 
+  # 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:
@@ -54,7 +54,7 @@ class Entity
     #   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 
+    #   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.
@@ -85,6 +85,46 @@ def self.exposures
       (@exposures ||= {})
     end
 
+    # This allows you to set a root element name for your representation.
+    #
+    # @param singular [String] the root key to use when representing a single object
+    # @param plural   [String] the root key to use when representing a collection of objects
+    #
+    # @example Entity Definition
+    #
+    #   module API
+    #     module Entities
+    #       class User < Grape::Entity
+    #         root 'user', 'users'
+    #         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
+    def self.root(singular, plural=nil)
+      @root = singular
+      @collection_root = plural
+    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,
@@ -95,11 +135,14 @@ def self.exposures
     # @param options [Hash] Options that will be passed through to each entity
     #   representation.
     def self.represent(objects, options = {})
-      if objects.is_a?(Array)
+      inner = if objects.is_a?(Array)
         objects.map{|o| self.new(o, {:collection => true}.merge(options))}
       else
         self.new(objects, options)
       end
+
+      root_element = objects.is_a?(Array) ? @collection_root : @root
+      root_element ? { root_element => inner } : inner
     end
 
     def initialize(object, options = {})

spec/grape/entity_spec.rb

@@ -59,6 +59,81 @@
       end
     end
 
+    describe '.root' do
+      context 'with singular and plural root keys' do
+        before(:each) do
+          subject.root 'thing', 'things'
+        end
+
+        context 'with a single object' do
+          it 'should allow a root element name to be specified' do
+            representation = subject.represent(Object.new)
+            representation.should be_kind_of(Hash)
+            representation.should have_key('thing')
+            representation['thing'].should be_kind_of(subject)
+          end
+        end
+
+        context 'with an array of objects' do
+          it 'should allow a root element name to be specified' do
+            representation = subject.represent(4.times.map{Object.new})
+            representation.should be_kind_of(Hash)
+            representation.should have_key('things')
+            representation['things'].should be_kind_of(Array)
+            representation['things'].size.should == 4
+            representation['things'].reject{|r| r.kind_of?(subject)}.should be_empty
+          end
+        end
+      end
+
+      context 'with singular root key' do
+        before(:each) do
+          subject.root 'thing'
+        end
+
+        context 'with a single object' do
+          it 'should allow a root element name to be specified' do
+            representation = subject.represent(Object.new)
+            representation.should be_kind_of(Hash)
+            representation.should have_key('thing')
+            representation['thing'].should be_kind_of(subject)
+          end
+        end
+
+        context 'with an array of objects' do
+          it 'should allow a root element name to be specified' do
+            representation = subject.represent(4.times.map{Object.new})
+            representation.should be_kind_of(Array)
+            representation.size.should == 4
+            representation.reject{|r| r.kind_of?(subject)}.should be_empty
+          end
+        end
+      end
+
+      context 'with plural root key' do
+        before(:each) do
+          subject.root nil, 'things'
+        end
+
+        context 'with a single object' do
+          it 'should allow a root element name to be specified' do
+            subject.represent(Object.new).should be_kind_of(subject)
+          end
+        end
+
+        context 'with an array of objects' do
+          it 'should allow a root element name to be specified' do
+            representation = subject.represent(4.times.map{Object.new})
+            representation.should be_kind_of(Hash)
+            representation.should have_key('things')
+            representation['things'].should be_kind_of(Array)
+            representation['things'].size.should == 4
+            representation['things'].reject{|r| r.kind_of?(subject)}.should be_empty
+          end
+        end
+      end
+    end
+
     describe '#initialize' do
       it 'should take an object and an optional options hash' do
         expect{ subject.new(Object.new) }.not_to raise_error
@@ -77,10 +152,10 @@
   context 'instance methods' do
     let(:model){ mock(attributes) }
     let(:attributes){ {
-      :name => 'Bob Bobson', 
+      :name => 'Bob Bobson',
       :email => '[email protected]',
       :friends => [
-        mock(:name => "Friend 1", :email => '[email protected]', :friends => []), 
+        mock(:name => "Friend 1", :email => '[email protected]', :friends => []),
         mock(:name => "Friend 2", :email => '[email protected]', :friends => [])
       ]
     } }