Merge branch 'master' of https://github.com/intridea/grape

Conflicts:
	CHANGELOG.markdown

Author: Ben Rosenblum

CHANGELOG.markdown

@@ -1,14 +1,19 @@
-Next Release
-============
+0.2.1 (7/11/2012)
+=================
 
 * [#181](https://github.com/intridea/grape/pull/181): Fix: Corrected JSON serialization of nested hashes containing `Grape::Entity` instances - [@benrosenblum](https://github.com/benrosenblum).
+* [#186](https://github.com/intridea/grape/issues/186): Fix: helpers allow multiple calls with modules and blocks - [@ppadron](https://github.com/ppadron).
+* [#188](https://github.com/intridea/grape/pull/188): Fix: multi-method routes append '(.:format)' only once - [@kainosnoema](https://github.com/kainosnoema).
 * [#64](https://github.com/intridea/grape/issues/64), [#180](https://github.com/intridea/grape/pull/180): Added support to get request bodies as parameters - [@bobbytables](https://github.com/bobbytables).
 * [#175](https://github.com/intridea/grape/pull/175): Added support for API versioning based on a request parameter - [@jackcasey](https://github.com/jackcasey).
 * [#168](https://github.com/intridea/grape/pull/168): Fix: Formatter can parse symbol keys in the headers hash - [@netmask](https://github.com/netmask).
 * [#169](https://github.com/intridea/grape/pull/169): Silence multi_json deprecation warnings - [@whiteley](https://github.com/whiteley).
 * [#166](https://github.com/intridea/grape/pull/166): Added support for `redirect`, including permanent and temporary - [@allenwei](https://github.com/allenwei).
 * [#159](https://github.com/intridea/grape/pull/159): Added `:requirements` to routes, allowing to use reserved characters in paths - [@gaiottino](https://github.com/gaiottino).
 * [#156](https://github.com/intridea/grape/pull/156): Added support for adding formatters to entities - [@bobbytables](https://github.com/bobbytables).
+* [#183](https://github.com/intridea/grape/pull/183): Added ability to include documentation in entities - [@flah00](https://github.com/flah00).
+* [#189](https://github.com/intridea/grape/pull/189): `HEAD` requests no longer return a body - [@stephencelis](https://github.com/stephencelis).
+* [#97](https://github.com/intridea/grape/issues/97): Allow overriding `Content-Type` - [@dblock](https://github.com/dblock).
 
 0.2.0 (3/28/2012)
 =================

README.markdown

@@ -77,9 +77,18 @@ class Twitter::API < Grape::API
 end
 ```
 
+Optionally, you can define requirements for your named route parameters using regular expressions. The route will match only if
+all requirements are met.
+
+```ruby
+get '/show/:id', :requirements => { :id => /[0-9]*/ } do
+  Tweet.find(params[:id])
+end
+```
+
 ## Mounting
 
-The above sample creates a Rack application that can be run from a rackup *config.ru* file 
+The above sample creates a Rack application that can be run from a rackup *config.ru* file
 with `rackup`:
 
 ``` ruby
@@ -119,7 +128,7 @@ There are three strategies in which clients can reach your API's endpoints: `:he
 version 'v1', :using => :header
 ```
 
-Using this versioning strategy, clients should pass the desired version in the HTTP Accept head. 
+Using this versioning strategy, clients should pass the desired version in the HTTP Accept head.
 
     curl -H Accept=application/vnd.twitter-v1+json http://localhost:9292/statuses/public_timeline
 
@@ -138,15 +147,15 @@ Using this versioning strategy, clients should pass the desired version in the U
 
     curl -H http://localhost:9292/v1/statuses/public_timeline
 
-Serialization takes place automatically. 
+Serialization takes place automatically.
 
 ### Param
 
 ```ruby
 version 'v1', :using => :param
 ```
 
-Using this versioning strategy, clients should pass the desired version as a request parameter, either in the URL query string or in the request body. 
+Using this versioning strategy, clients should pass the desired version as a request parameter, either in the URL query string or in the request body.
 
     curl -H http://localhost:9292/events?apiver=v1
 
@@ -160,7 +169,7 @@ version 'v1', :using => :param, :parameter => "v"
 
 ## Parameters
 
-Parameters are available through the `params` hash object. This includes `GET` and `POST` parameters, 
+Parameters are available through the `params` hash object. This includes `GET` and `POST` parameters,
 along with any named parameters you specify in your route strings.
 
 ```ruby
@@ -345,6 +354,51 @@ class Twitter::API < Grape::API
 end
 ```
 
+## Logging
+
+`Grape::API` provides a `logger` method which by default will return an instance of the `Logger`
+class from Ruby's standard library.
+
+To log messages from within an endpoint, you need to define a helper to make the logger
+available in the endpoint context:
+
+``` ruby
+class API < Grape::API
+  helpers do
+    def logger
+      API.logger
+    end
+  end
+  get '/hello' do
+    logger.info "someone said hello"
+    "hey there"
+  end
+end
+```
+
+You can also set your own logger:
+
+``` ruby
+class MyLogger
+  def warning(message)
+    puts "this is a warning: #{message}"
+  end
+end
+
+class API < Grape::API
+  logger MyLogger.new
+  helpers do
+    def logger
+      API.logger
+    end
+  end
+  get '/hello' do
+    logger.warning "someone said hello"
+    "hey there"
+  end
+end
+```
+
 ## Content-Types
 
 By default, Grape supports _XML_, _JSON_, _Atom_, _RSS_, and _text_ content-types.
@@ -372,9 +426,20 @@ class Twitter::API < Grape::API
 end
 ```
 
+You can override the content-type by setting the `Content-Type` header.
+
+``` ruby
+class API < Grape::API
+  get '/script' do
+    content_type "application/javascript"
+    "var x = 1;"
+  end
+end
+```
+
 ## Writing Tests
 
-You can test a Grape API with RSpec by making HTTP requests and examining the response. 
+You can test a Grape API with RSpec by making HTTP requests and examining the response.
 
 ### Writing Tests with Rack
 
@@ -443,11 +508,122 @@ RSpec.configure do |config|
 end
 ```
 
+## 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 Grape::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)
+  * `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
+
+``` ruby
+module API
+  module Entities
+    class User < Grape::Entity
+      expose :first_name, :last_name
+      expose :field, :documentation => {:type => "string", :desc => "words go here"}
+      expose :email, :if => {:type => :full}
+      expose :user_type, user_id, :if => lambda{|user,options| user.confirmed?}
+      expose(:name){|user,options| [user.first_name, user.last_name].join(' ')}
+      expose :latest_status, :using => API::Status, :as => :status
+    end
+  end
+end
+
+module API
+  module Entities
+    class UserDetailed < API::Entities::User
+      expose :account_id
+    end
+  end
+end
+```
+
+### 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.
+
+``` ruby
+module API
+  class Users < Grape::API
+    version 'v1'
+
+    desc 'User index', {
+      :object_fields => 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
+```
+
+### Caveats
+
+Entities with duplicate exposure names and conditions will silently overwrite one another.
+In the following example, when object#check equals "foo", only afield will be exposed.
+However, when object#check equals "bar" both bfield and foo will be exposed.
+
+```ruby
+module API
+  module Entities
+    class User < Grape::Entity
+      expose :afield, :foo, :if => lambda{|object,options| object.check=="foo"}
+      expose :bfield, :foo, :if => lambda{|object,options| object.check=="bar"}
+    end
+  end
+end
+```
+
+This can be problematic, when you have mixed collections. Using #respond_to? is safer.
+
+```ruby
+module API
+  module Entities
+    class User < Grape::Entity
+      expose :afield, :if => lambda{|object,options| object.check=="foo"}
+      expose :bfield, :if => lambda{|object,options| object.check=="bar"}
+      expose :foo, :if => lambda{object,options| object.respond_to?(:foo)}
+    end
+  end
+end
+```
+
 ## Describing and Inspecting an API
 
 Grape lets you add a description to an API along with any other optional
 elements that can also be inspected at runtime.
-This can be useful for generating documentation.
+This can be useful for generating documentation. If the response
+requires documentation, consider using an entity.
 
 ``` ruby
 class TwitterAPI < Grape::API
@@ -485,13 +661,13 @@ Parameters can also be tagged to the method declaration itself.
 
 ``` ruby
 class StringAPI < Grape::API
-  get "split/:string", { :params => [ "token" ], :optional_params => [ "limit" ] } do
+  get "split/:string", { :params => { "token" => "a token" }, :optional_params => { "limit" => "the limit" } } do
     params[:string].split(params[:token], (params[:limit] || 0))
   end
 end
 
-StringAPI::routes[0].route_params # yields an array [ "string", "token" ]
-StringAPI::routes[0].route_optional_params # yields an array [ "limit" ]
+StringAPI::routes[0].route_params # yields a hash {"string" => "", "token" => "a token"}
+StringAPI::routes[0].route_optional_params # yields a hash {"limit" => "the limit"}
 ```
 
 It's possible to retrieve the information about the current route from within an API call with `route`.
@@ -505,6 +681,33 @@ class MyAPI < Grape::API
 end
 ```
 
+You can use this information to create a helper that will check if the request has
+all required parameters:
+
+``` ruby
+class MyAPI < Grape::API
+
+  helpers do
+    def validate_request!
+      # skip validation if no parameter is declared
+      return unless route.route_params
+      route.route_params.each do |k, v|
+        if !params.has_key? k
+          error!("Missing field: #{k}", 400)
+        end
+      end
+    end
+  end
+
+  before { validate_request! }
+
+  desc "creates a new item resource", :params => { :name => 'name is a required parameter' }
+  post :items do
+    ...
+  end
+end
+```
+
 ## Anchoring
 
 Grape by default anchors all request paths, which means that the request URL

lib/grape/api.rb

@@ -208,9 +208,14 @@ def represent(model_class, options)
       #         end
       #       end
       #     end
-      def helpers(mod = nil, &block)
-        if block_given? || mod
-          mod ||= settings.peek[:helpers] || Module.new
+      def helpers(new_mod = nil, &block)
+        if block_given? || new_mod
+          mod = settings.peek[:helpers] || Module.new
+          if new_mod
+            mod.class_eval do
+              include new_mod
+            end
+          end
           mod.class_eval &block if block_given?
           set(:helpers, mod)
         else

lib/grape/endpoint.rb

@@ -85,8 +85,7 @@ def prepare_path(path)
       parts << ':version' if settings[:version] && settings[:version_options][:using] == :path
       parts << namespace.to_s if namespace
       parts << path.to_s if path && '/' != path
-      parts.last << '(.:format)'
-      Rack::Mount::Utils.normalize_path(parts.join('/'))
+      Rack::Mount::Utils.normalize_path(parts.join('/') + '(.:format)')
     end
 
     def namespace
@@ -153,7 +152,7 @@ def error!(message, status=403)
     end
 
     # Redirect to a new url.
-    # 
+    #
     # @param url [String] The url to be redirect.
     # @param options [Hash] The options used when redirect.
     #                       :permanent, default true.
@@ -164,7 +163,7 @@ def redirect(url, options = {})
       else
         if env['HTTP_VERSION'] == 'HTTP/1.1' && request.request_method.to_s.upcase != "GET"
           status 303
-        else 
+        else
           status 302
         end
       end
@@ -198,7 +197,12 @@ def header(key = nil, val = nil)
         @header
       end
     end
-
+    
+    # Set response content-type
+    def content_type(val)
+      header('Content-Type', val)
+    end
+    
     # Set or get a cookie
     #
     # @example
@@ -297,6 +301,7 @@ def run(env)
     def build_middleware
       b = Rack::Builder.new
 
+      b.use Rack::Head
       b.use Grape::Middleware::Error,
         :default_status => settings[:default_error_status] || 403,
         :rescue_all => settings[:rescue_all],