grape 0.2.1.1 → 0.2.2

data/.gitignore

@@ -16,6 +16,7 @@ tmtags
 
 ## VIM
 *.swp
+*.swo
 
 ## RUBYMINE
 .idea

data/CHANGELOG.markdown

@@ -1,6 +1,27 @@
-0.2.1.1 (1/11/2013)
+0.2.2 (Next Release)
 ====================
-* Fix: CVE-2013-0175, `multi_xml` parse vulnerability, require 'multi_xml' 0.5.2 - [@dblock](http://github.com/dblock).
+
+Features
+--------
+
+* [#201](https://github.com/intridea/grape/pull/201), [#236](https://github.com/intridea/grape/pull/236), [#221](https://github.com/intridea/grape/pull/221): Added coercion and validations support to `params` DSL - [@schmurfy](https://github.com/schmurfy), [@tim-vandecasteele](https://github.com/tim-vandecasteele), [@adamgotterer](https://github.com/adamgotterer).
+* [#204](https://github.com/intridea/grape/pull/204): Added ability to declare shared `params` at `namespace` level - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* [#234](https://github.com/intridea/grape/pull/234): Added a DSL for creating entities via mixin - [@mbleigh](https://github.com/mbleigh).
+* [#240](https://github.com/intridea/grape/pull/240): Define API response format from a query string `format` parameter, if specified - [@neetiraj](https://github.com/neetiraj).
+* Adds Endpoint#declared to easily filter out unexpected params. - [@mbleigh](https://github.com/mbleigh)
+
+Fixes
+-----
+
+* [#248](https://github.com/intridea/grape/pull/248): Fix: API `version` returns last version set - [@narkoz](https://github.com/narkoz).
+* [#242](https://github.com/intridea/grape/issues/242): Fix: permanent redirect status should be `301`, was `304` - [@adamgotterer](https://github.com/adamgotterer).
+* [#211](https://github.com/intridea/grape/pull/211): Fix: custom validations are no longer triggered when optional and parameter is not present - [@adamgotterer](https://github.com/adamgotterer).
+* [#210](https://github.com/intridea/grape/pull/210): Fix: `Endpoint#body_params` causing undefined method 'size' - [@adamgotterer](https://github.com/adamgotterer).
+* [#205](https://github.com/intridea/grape/pull/205): Fix: Corrected parsing of empty JSON body on POST/PUT - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* [#181](https://github.com/intridea/grape/pull/181): Fix: Corrected JSON serialization of nested hashes containing `Grape::Entity` instances - [@benrosenblum](https://github.com/benrosenblum).
+* [#203](https://github.com/intridea/grape/pull/203): Added a check to `Entity#serializable_hash` that verifies an entity exists on an object - [@adamgotterer](https://github.com/adamgotterer).
+* [#208](https://github.com/intridea/grape/pull/208): `Entity#serializable_hash` must also check if attribute is generated by a user supplied block - [@ppadron](https://github.com/ppadron).
+* [#252](https://github.com/intridea/grape/pull/252): Resources that don't respond to a requested HTTP method return 405 (Method Not Allowed) instead of 404 (Not Found) [@simulacre](https://github.com/simulacre)
 
 0.2.1 (7/11/2012)
 =================

data/Gemfile

@@ -10,4 +10,6 @@ group :development, :test do
   gem 'rb-fsevent'
   gem 'growl'
   gem 'json'
+  gem 'rspec' 
+  gem 'rack-test', "~> 0.6.2", :require => "rack/test"
 end

data/README.markdown

@@ -1,12 +1,14 @@
-# Grape [![Build Status](http://travis-ci.org/intridea/grape.png?branch=frontier)](http://travis-ci.org/intridea/grape)
+![grape logo](https://github.com/intridea/grape/wiki/grape_logo.png)
 
 ## What is Grape?
 
-Grape is a REST-like API micro-framework for Ruby. It is built to complement
-existing web application frameworks such as Rails and Sinatra by providing a
-simple DSL to easily provide APIs. It has built-in support for common
-conventions such as multiple formats, subdomain/prefix restriction, and
-versioning.
+Grape is a REST-like API micro-framework for Ruby. It's designed to run on Rack
+or complement existing web application frameworks such as Rails and Sinatra by 
+providing a simple DSL to easily develop RESTful APIs. It has built-in support 
+for common conventions, including multiple formats, subdomain/prefix restriction, 
+content negotiation, versioning and much more.
+
+[![Build Status](https://travis-ci.org/intridea/grape.png?branch=master)](http://travis-ci.org/intridea/grape)
 
 ## Project Tracking
 
@@ -23,6 +25,8 @@ If you're using Bundler, add the gem to Gemfile.
 
     gem 'grape'
 
+Run `bundle install`.
+
 ## Basic Usage
 
 Grape APIs are Rack applications that are created by subclassing `Grape::API`.
@@ -32,6 +36,7 @@ the context of recreating parts of the Twitter API.
 ``` ruby
 class Twitter::API < Grape::API
   version 'v1', :using => :header, :vendor => 'twitter'
+  format :json
 
   helpers do
     def current_user
@@ -44,19 +49,30 @@ class Twitter::API < Grape::API
   end
 
   resource :statuses do
+  
+    desc "Returns a public timeline."
     get :public_timeline do
       Tweet.limit(20)
     end
 
+    desc "Returns a personal timeline."
     get :home_timeline do
       authenticate!
       current_user.home_timeline
     end
 
+    desc "Returns a tweet."
+    params do
+      requires :id, :type => Integer, :desc => "Tweet id."
+    end
     get '/show/:id' do
       Tweet.find(params[:id])
     end
-
+    
+    desc "Creates a tweet."
+    params do
+      requires :status, :type => String, :desc => "Your status."
+    end
     post :update do
       authenticate!
       Tweet.create(
@@ -66,28 +82,13 @@ class Twitter::API < Grape::API
     end
   end
 
-  resource :account do
-    before { authenticate! }
-
-    get '/private' do
-      "Congratulations, you found the secret!"
-    end
-  end
-
-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
 
+### Rack
+
 The above sample creates a Rack application that can be run from a rackup *config.ru* file
 with `rackup`:
 
@@ -102,13 +103,21 @@ And would respond to the following routes:
     GET  /statuses/show/:id(.json)
     POST /statuses/update(.json)
 
+### Rails
+
 In a Rails application, modify *config/routes*:
 
 ``` ruby
 mount Twitter::API => "/"
 ```
 
-You can mount multiple API implementations inside another one.
+Note that you will need to restart Rails to pick up changes in your API classes
+(see [Issue 131](https://github.com/intridea/grape/issues/131)).
+
+### Modules
+
+You can mount multiple API implementations inside another one. These don't have to be
+different versions, but may be components of the same API.
 
 ```ruby
 class Twitter::API < Grape::API
@@ -119,23 +128,23 @@ end
 
 ## Versioning
 
-There are three strategies in which clients can reach your API's endpoints: `:header`, `:path` and `:param`. The default strategy is `:header`.
-
+There are three strategies in which clients can reach your API's endpoints: `:header`, 
+`:path` and `:param`. The default strategy is `:path`.
 
 ### Header
 
 ```ruby
-version 'v1', :using => :header
+version 'v1', :using => :header, :vendor => 'twitter'
 ```
 
-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
 
-By default, the first matching version is used when no Accept header is
+By default, the first matching version is used when no `Accept` header is
 supplied. This behavior is similar to routing in Rails. To circumvent this default behavior,
-one could use the `:strict` option. When this option is set to `true`, a `404 Not found` error
-is returned when no correct Accept header is supplied.
+one could use the `:strict` option. When this option is set to `true`, a `406 Not Acceptable` error
+is returned when no correct `Accept` header is supplied.
 
 ### Path
 
@@ -147,19 +156,18 @@ 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.
-
 ### 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
 
-The default name for the query parameter is 'apiver' but can be specified using the :parameter option.
+The default name for the query parameter is 'apiver' but can be specified using the `:parameter` option.
 
 ```ruby
 version 'v1', :using => :param, :parameter => "v"
@@ -167,14 +175,25 @@ version 'v1', :using => :param, :parameter => "v"
 
     curl -H http://localhost:9292/events?v=v1
 
+## Describing Methods
+
+You can add a description to API methods and namespaces.
+
+``` ruby
+desc "Returns a reticulated spline."
+get "spline/:id" do
+  Spline.find(params[:id])
+end
+```
+
 ## Parameters
 
-Parameters are available through the `params` hash object. This includes `GET` and `POST` parameters,
+Request 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
 get do
-    Article.order(params[:sort_by])
+  Article.order(params[:sort_by])
 end
 ```
 
@@ -192,9 +211,113 @@ post '/json_endpoint' do
 end
 ```
 
+## Parameter Validation and Coercion
+
+You can define validations and coercion options for your parameters using a `params` block.
+
+```ruby
+params do
+  requires :id, type: Integer
+  optional :name, type: String, regexp: /^[a-z]+$/
+
+  group :user do
+    requires :first_name
+    requires :last_name
+  end
+end
+get ':id' do
+  # params[:id] is an Integer
+end
+```
+
+When a type is specified an implicit validation is done after the coercion to ensure 
+the output type is the one declared.
+
+Parameters can be nested using `group`. In the above example, this means both
+`params[:user][:first_name]` and `params[:user][:last_name]` are required next to `params[:id]`.
+
+### Namespace Validation and Coercion
+Namespaces allow parameter definitions and apply to every method within the namespace.
+
+```ruby
+namespace :shelves do
+  params do
+    requires :shelf_id, type: Integer, desc: "A shelf."
+  end
+  namespace ":shelf_id" do
+    desc "Retrieve a book from a shelf."
+    params do
+      requires :book_id, type: Integer, desc: "A book."
+    end
+    get ":book_id" do
+      # params[:shelf_id] defines a shelf
+      # params[:book_id] defines a book
+    end
+  end
+end
+```
+
+### Custom Validators
+```ruby
+class AlphaNumeric < Grape::Validations::Validator
+  def validate_param!(attr_name, params)
+    unless params[attr_name] =~ /^[[:alnum:]]+$/
+      throw :error, :status => 400, :message => "#{attr_name}: must consist of alpha-numeric characters"
+    end    
+  end
+end  
+```
+
+```ruby
+params do
+  requires :username, :alpha_numeric => true
+end
+```
+
+You can also create custom classes that take parameters.
+
+```ruby
+class Length < Grape::Validations::SingleOptionValidator
+  def validate_param!(attr_name, params)
+    unless params[attr_name].length == @option
+      throw :error, :status => 400, :message => "#{attr_name}: must be #{@option} characters long"
+    end    
+  end
+end  
+``` 
+
+```ruby
+params do
+  requires :name, :length => 5
+end
+```
+
+### Validation Errors
+
+When validation and coercion erros occur an exception of type `ValidationError` is raised.
+If the exception goes uncaught it will respond with a status of 400 and an error message.
+You can rescue a `ValidationError` and respond with a custom response.
+
+```ruby
+rescue_from ValidationError do |e|
+    Rack::Response.new({
+        'status' => e.status,
+        'message' => e.message,
+        'param' => e.param
+    }.to_json, e.status)    
+end 
+```
+
 ## Headers
 
-Headers are available through the `env` hash object.
+Headers are available through the `header` helper or the `env` hash object.
+
+```ruby
+get do
+    content_type = header['Content-type']
+    ...
+end
+```
 
 ```ruby
 get do
@@ -203,10 +326,21 @@ get do
 end
 ```
 
+## Routes
+
+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
+```
+
 ## Helpers
 
 You can define helper methods that your endpoints can use with the `helpers`
-macro by either giving a block or a module:
+macro by either giving a block or a module.
 
 ``` ruby
 module MyHelpers
@@ -235,7 +369,7 @@ end
 
 ## Cookies
 
-You can set, get and delete your cookies very simply using `cookies` method:
+You can set, get and delete your cookies very simply using `cookies` method.
 
 ``` ruby
 class API < Grape::API
@@ -251,7 +385,7 @@ class API < Grape::API
 end
 ```
 
-To set more than value use hash-based syntax:
+To set more than value use hash-based syntax.
 
 ``` ruby
 cookies[:counter] = {
@@ -262,30 +396,73 @@ cookies[:counter] = {
 }
 cookies[:counter][:value] +=1
 ```
-## Redirect
 
-You can redirect to a new url
+## Redirecting
+
+You can redirect to a new url temporarily (302) or permanently (301).
 
 ``` ruby
 redirect "/new_url"
 ```
 
-use permanent redirect
-
 ``` ruby
 redirect "/new_url", :permanent => true
 ```
 
-## Raising Errors
+## Allowed Methods
 
-You can raise errors explicitly.
+When you add a route for a resource, a route for the HTTP OPTIONS
+method will also be added. The response to an OPTIONS request will
+include an Allow header listing the supported methods.
+
+``` ruby
+class API < Grape::API
+  get '/counter' do
+    { :counter => Counter.count }
+  end
+
+  params do
+    requires :value, :type => Integer, :desc => 'value to add to counter'
+  end
+  put '/counter' do
+    { :counter => Counter.incr(params.value) }
+  end
+end
+```
+
+``` shell
+curl -v -X OPTIONS http://localhost:3000/counter 
+
+> OPTIONS /counter HTTP/1.1
+> 
+< HTTP/1.1 204 No Content
+< Allow: OPTIONS, GET, PUT
+```
+
+
+If a request for a resource is made with an unsupported HTTP method, an
+HTTP 405 (Method Not Allowed) response will be returned.
+
+``` shell
+curl -X DELETE -v http://localhost:3000/counter/
+
+> DELETE /counter/ HTTP/1.1
+> Host: localhost:3000
+> 
+< HTTP/1.1 405 Method Not Allowed
+< Allow: OPTIONS, GET, PUT
+```
+
+## Raising Exceptions
+
+You can abort the execution of an API method by raising errors with `error!`.
 
 ``` ruby
 error!("Access Denied", 401)
 ```
 
-You can also return JSON formatted objects explicitly by raising error! and
-passing a hash instead of a message.
+You can also return JSON formatted objects by raising error! and passing a hash
+instead of a message.
 
 ``` ruby
 error!({ "error" => "unexpected error", "detail" => "missing widget" }, 500)
@@ -294,7 +471,7 @@ error!({ "error" => "unexpected error", "detail" => "missing widget" }, 500)
 ## Exception Handling
 
 Grape can be told to rescue all exceptions and instead return them in
-text or json formats.
+txt or json formats.
 
 ``` ruby
 class Twitter::API < Grape::API
@@ -360,7 +537,7 @@ end
 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:
+available in the endpoint context.
 
 ``` ruby
 class API < Grape::API
@@ -376,7 +553,7 @@ class API < Grape::API
 end
 ```
 
-You can also set your own logger:
+You can also set your own logger.
 
 ``` ruby
 class MyLogger
@@ -402,8 +579,10 @@ end
 ## Content-Types
 
 By default, Grape supports _XML_, _JSON_, _Atom_, _RSS_, and _text_ content-types.
+Serialization takes place automatically.
+
 Your API can declare additional types to support. Response format is determined by the
-request's extension or `Accept` header.
+request's extension, an explicit `format` parameter in the query string, or `Accept` header.
 
 ``` ruby
 class Twitter::API < Grape::API
@@ -414,7 +593,8 @@ end
 You can also set the default format. The order for choosing the format is the following.
 
 * Use the file extension, if specified. If the file is .json, choose the JSON format.
-* Use the format, if specified by the `format` option.
+* Use the value of the `format` parameter in the query string, if specified.
+* Use the format set by the `format` option, if specified.
 * Attempt to find an acceptable format from the `Accept` header.
 * Use the default format, if specified by the `default_format` option.
 * Default to `:txt` otherwise.
@@ -422,6 +602,11 @@ You can also set the default format. The order for choosing the format is the fo
 ``` ruby
 class Twitter::API < Grape::API
   format :json
+end
+```
+
+``` ruby
+class Twitter::API < Grape::API
   default_format :json
 end
 ```
@@ -437,77 +622,6 @@ class API < Grape::API
 end
 ```
 
-## Writing Tests
-
-You can test a Grape API with RSpec by making HTTP requests and examining the response.
-
-### Writing Tests with Rack
-
-Use `rack-test` and define your API as `app`.
-
-```ruby
-require 'spec_helper'
-
-describe Twitter::API do
-  include Rack::Test::Methods
-
-  def app
-    Twitter::API
-  end
-
-  describe Twitter::API do
-    describe "GET /api/v1/statuses" do
-      it "returns an empty array of statuses" do
-        get "/api/v1/statuses"
-        last_response.status.should == 200
-        JSON.parse(response.body).should == []
-      end
-    end
-    describe "GET /api/v1/statuses/:id" do
-      it "returns a status by id" do
-        status = Status.create!
-        get "/api/v1/statuses/#{status.id}"
-        last_response.body.should == status.to_json
-      end
-    end
-  end
-end
-```
-
-### Writing Tests with Rails
-
-``` ruby
-require 'spec_helper'
-
-describe Twitter::API do
-  describe "GET /api/v1/statuses" do
-    it "returns an empty array of statuses" do
-      get "/api/v1/statuses"
-      response.status.should == 200
-      JSON.parse(response.body).should == []
-    end
-  end
-  describe "GET /api/v1/statuses/:id" do
-    it "returns a status by id" do
-      status = Status.create!
-      get "/api/v1/statuses/#{status.id}"
-      resonse.body.should == status.to_json
-    end
-  end
-end
-```
-
-In Rails, HTTP request tests would go into the `spec/request` group. You may want your API code to go into
-`app/api` - you can match that layout under `spec` by adding the following in `spec/spec_helper.rb`.
-
-```ruby
-RSpec.configure do |config|
-  config.include RSpec::Rails::RequestExampleGroup, :type => :request, :example_group => {
-    :file_path => /spec\/api/
-  }
-end
-```
-
 ## Reusable Responses with Entities
 
 Entities are a reusable means for converting Ruby objects to API responses.
@@ -518,22 +632,22 @@ ever larger responses, using inheritance.
 
 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
+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}`
+    * 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"}`
+    * `: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
+    * `: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
@@ -544,10 +658,10 @@ 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 :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
@@ -562,11 +676,32 @@ module API
 end
 ```
 
+#### Using the Exposure DSL
+
+Grape ships with a DSL to easily define entities within the context
+of an existing class:
+
+```ruby
+class User
+  include Grape::Entity::DSL
+
+  entity :name, :email do
+    expose :advanced, if: :conditional
+  end
+end
+```
+
+The above will automatically create a `User::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
+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.
+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.
 
@@ -587,32 +722,58 @@ module API
 end
 ```
 
+### Entity Organization
+
+In addition to separately organizing entities, it may be useful to
+put them as namespaced classes underneath the model they represent.
+For example:
+
+```ruby
+class User
+  def entity
+    Entity.new(self)
+  end
+
+  class Entity < Grape::Entity
+    expose :name, :email
+  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 `User::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 afield will be exposed.
-However, when object#check equals "bar" both bfield and foo will be exposed.
+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.
 
 ```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"}
+      expose :field_a, :foo, :if => lambda { |object, options| object.check == "foo" }
+      expose :field_b, :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.
+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)}
+      expose :field_a, :if => lambda { |object, options| object.check == "foo" }
+      expose :field_b, :if => lambda { |object, options| object.check == "bar" }
+      expose :foo, :if => lambda { |object, options| object.respond_to?(:foo) }
     end
   end
 end
@@ -620,31 +781,10 @@ 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. If the response
-requires documentation, consider using an entity.
-
-``` ruby
-class TwitterAPI < Grape::API
-
-  version 'v1'
-
-  desc "Retrieves the API version number."
-  get "version" do
-    api.version
-  end
-
-  desc "Reverses a string.", { :params =>
-    { "s" => { :desc => "string to reverse", :type => "string" }}
-  }
-  get "reverse" do
-    params[:s].reverse
-  end
-end
-```
+Grape routes can be reflected at runtime. This can notably be useful for generating 
+documentation.
 
-Grape then exposes arrays of API versions and compiled routes. Each route
+Grape exposes arrays of API versions and compiled routes. Each route
 contains a `route_prefix`, `route_version`, `route_namespace`, `route_method`,
 `route_path` and `route_params`. The description and the optional hash that
 follows the API path may contain any number of keys and its values are also
@@ -654,56 +794,20 @@ accessible via dynamically-generated `route_[name]` functions.
 TwitterAPI::versions # yields [ 'v1', 'v2' ]
 TwitterAPI::routes # yields an array of Grape::Route objects
 TwitterAPI::routes[0].route_version # yields 'v1'
-TwitterAPI::routes[0].route_description # yields [ { "s" => { :desc => "string to reverse", :type => "string" }} ]
+TwitterAPI::routes[0].route_description # etc.
 ```
 
-Parameters can also be tagged to the method declaration itself.
-
-``` ruby
-class StringAPI < Grape::API
-  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 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`.
+It's possible to retrieve the information about the current route from within an API 
+call with `route`.
 
 ``` ruby
 class MyAPI < Grape::API
-  desc "Returns a description of a parameter.", { :params => { "id" => "a required id" } }
-  get "params/:id" do
-    route.route_params[params[:id]] # returns "a required id"
-  end
-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
+  desc "Returns a description of a parameter."
+  params do
+    requires :id, :type => Integer, :desc => "Identity."
   end
-
-  before { validate_request! }
-
-  desc "creates a new item resource", :params => { :name => 'name is a required parameter' }
-  post :items do
-    ...
+  get "params/:id" do
+    route.route_params[params[:id]] # yields the parameter description
   end
 end
 ```
@@ -712,12 +816,10 @@ end
 
 Grape by default anchors all request paths, which means that the request URL
 should match from start to end to match, otherwise a `404 Not Found` is
-returned.
-However, this is sometimes not what you want, because it is not always known up
-front what can be expected from the call.
-This is because Rack-mount by default anchors requests to match from the start
-to the end, or not at all. Rails solves this problem by using a `:anchor =>
-false` option in your routes.
+returned. However, this is sometimes not what you want, because it is not always 
+known upfront what can be expected from the call. This is because Rack-mount by
+default anchors requests to match from the start to the end, or not at all. 
+Rails solves this problem by using a `:anchor => false` option in your routes.
 In Grape this option can be used as well when a method is defined.
 
 For instance when you're API needs to get part of an URL, for instance:
@@ -739,13 +841,87 @@ specification and using the `PATH_INFO` Rack environment variable, using
 `env["PATH_INFO"]`. This will hold everything that comes after the '/urls/'
 part.
 
-## Note on Patches/Pull Requests
+## Writing Tests
+
+You can test a Grape API with RSpec by making HTTP requests and examining the response.
+
+### Writing Tests with Rack
+
+Use `rack-test` and define your API as `app`.
+
+```ruby
+require 'spec_helper'
+
+describe Twitter::API do
+  include Rack::Test::Methods
+
+  def app
+    Twitter::API
+  end
+
+  describe Twitter::API do
+    describe "GET /api/v1/statuses" do
+      it "returns an empty array of statuses" do
+        get "/api/v1/statuses"
+        last_response.status.should == 200
+        JSON.parse(response.body).should == []
+      end
+    end
+    describe "GET /api/v1/statuses/:id" do
+      it "returns a status by id" do
+        status = Status.create!
+        get "/api/v1/statuses/#{status.id}"
+        last_response.body.should == status.to_json
+      end
+    end
+  end
+end
+```
+
+### Writing Tests with Rails
+
+``` ruby
+require 'spec_helper'
+
+describe Twitter::API do
+  describe "GET /api/v1/statuses" do
+    it "returns an empty array of statuses" do
+      get "/api/v1/statuses"
+      response.status.should == 200
+      JSON.parse(response.body).should == []
+    end
+  end
+  describe "GET /api/v1/statuses/:id" do
+    it "returns a status by id" do
+      status = Status.create!
+      get "/api/v1/statuses/#{status.id}"
+      resonse.body.should == status.to_json
+    end
+  end
+end
+```
+
+In Rails, HTTP request tests would go into the `spec/request` group. You may want your API code to go into
+`app/api` - you can match that layout under `spec` by adding the following in `spec/spec_helper.rb`.
+
+```ruby
+RSpec.configure do |config|
+  config.include RSpec::Rails::RequestExampleGroup, :type => :request, :example_group => {
+    :file_path => /spec\/api/
+  }
+end
+```
+
+## Contributing to Grape
+
+Grape is work of dozens of contributors. You're encouraged to submit pull requests, propose
+features and discuss issues.
 
 * Fork the project
 * Write tests for your new feature or a test that reproduces a bug
 * Implement your feature or make a bug fix
 * Do not mess with Rakefile, version or history
-* Commit, push and make a pull request. Bonus points for topical branches.
+* Commit, push and make a pull request. Bonus points for topic branches.
 
 ## License
 
@@ -753,5 +929,4 @@ MIT License. See LICENSE for details.
 
 ## Copyright
 
-Copyright (c) 2010-2012 Michael Bleigh and Intridea, Inc.
-
+Copyright (c) 2010-2012 Michael Bleigh, and Intridea, Inc.