grape 0.3.0 → 0.7.0

data/README.md

@@ -8,16 +8,15 @@ 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)
+[![Build Status](https://travis-ci.org/intridea/grape.png?branch=master)](http://travis-ci.org/intridea/grape) [![Code Climate](https://codeclimate.com/github/intridea/grape.png)](https://codeclimate.com/github/intridea/grape) [![Inline docs](http://inch-pages.github.io/github/intridea/grape.png)](http://inch-pages.github.io/github/intridea/grape) [![Dependency Status](https://www.versioneye.com/ruby/grape/0.6.1/badge.png)](https://www.versioneye.com/ruby/grape/0.6.1)
 
 ## Stable Release
 
-You're reading the documentation for the next release of Grape, which should be 0.3.
-The current stable release is [0.2.6](https://github.com/intridea/grape/blob/v0.2.6/README.markdown).
+You're reading the documentation for the stable release of Grape, 0.7.0.
 
-## Project Tracking
+## Project Resources
 
-* [Grape Google Group](http://groups.google.com/group/ruby-grape)
+* Need help? [Grape Google Group](http://groups.google.com/group/ruby-grape)
 * [Grape Wiki](https://github.com/intridea/grape/wiki)
 
 ## Installation
@@ -41,8 +40,7 @@ the context of recreating parts of the Twitter API.
 ```ruby
 module Twitter
   class API < Grape::API
-
-    version 'v1', :using => :header, :vendor => 'twitter'
+    version 'v1', using: :header, vendor: 'twitter'
     format :json
 
     helpers do
@@ -56,7 +54,6 @@ module Twitter
     end
 
     resource :statuses do
-
       desc "Return a public timeline."
       get :public_timeline do
         Status.limit(20)
@@ -70,46 +67,47 @@ module Twitter
 
       desc "Return a status."
       params do
-        requires :id, :type => Integer, :desc => "Status id."
+        requires :id, type: Integer, desc: "Status id."
       end
-      get ':id' do
-        Status.find(params[:id])
+      route_param :id do
+        get do
+          Status.find(params[:id])
+        end
       end
 
       desc "Create a status."
       params do
-        requires :status, :type => String, :desc => "Your status."
+        requires :status, type: String, desc: "Your status."
       end
       post do
         authenticate!
         Status.create!({
-          :user => current_user,
-          :text => params[:status]
+          user: current_user,
+          text: params[:status]
         })
       end
 
       desc "Update a status."
       params do
-        requires :id, :type => String, :desc => "Status ID."
-        requires :status, :type => String, :desc => "Your status."
+        requires :id, type: String, desc: "Status ID."
+        requires :status, type: String, desc: "Your status."
       end
       put ':id' do
         authenticate!
         current_user.statuses.find(params[:id]).update({
-          :user => current_user,
-          :text => params[:status]
+          user: current_user,
+          text: params[:status]
         })
       end
 
       desc "Delete a status."
       params do
-        requires :id, :type => String, :desc => "Status ID."
+        requires :id, type: String, desc: "Status ID."
       end
       delete ':id' do
         authenticate!
         current_user.statuses.find(params[:id]).destroy
       end
-
     end
   end
 end
@@ -137,13 +135,40 @@ And would respond to the following routes:
 
 Grape will also automatically respond to HEAD and OPTIONS for all GET, and just OPTIONS for all other routes.
 
+### Alongside Sinatra (or other frameworks)
+
+If you wish to mount Grape alongside another Rack framework such as Sinatra, you can do so easily using
+`Rack::Cascade`:
+
+```ruby
+# Example config.ru
+
+require 'sinatra'
+require 'grape'
+
+class API < Grape::API
+  get :hello do
+    { hello: "world" }
+  end
+end
+
+class Web < Sinatra::Base
+  get '/' do
+    "Hello world."
+  end
+end
+
+use Rack::Session::Cookie
+run Rack::Cascade.new [API, Web]
+```
+
 ### Rails
 
 Place API files into `app/api` and modify `application.rb`.
 
 ```ruby
-config.paths.add "app/api", :glob => "**/*.rb"
-config.autoload_paths += Dir["#{Rails.root}/app/api/*"]
+config.paths.add File.join('app', 'api'), glob: File.join('**', '*.rb')
+config.autoload_paths += Dir[Rails.root.join('app', 'api', '*')]
 ```
 
 Modify `config/routes`:
@@ -176,13 +201,13 @@ end
 
 ## Versioning
 
-There are three strategies in which clients can reach your API's endpoints: `:path`,
-`:header` and `:param`. The default strategy is `:path`.
+There are four strategies in which clients can reach your API's endpoints: `:path`,
+`:header`, `:accept_version_header` and `:param`. The default strategy is `:path`.
 
 ### Path
 
 ```ruby
-version 'v1', :using => :path
+version 'v1', using: :path
 ```
 
 Using this versioning strategy, clients should pass the desired version in the URL.
@@ -192,22 +217,41 @@ Using this versioning strategy, clients should pass the desired version in the U
 ### Header
 
 ```ruby
-version 'v1', :using => :header, :vendor => 'twitter'
+version 'v1', using: :header, vendor: 'twitter'
 ```
 
 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
+    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
 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 `406 Not Acceptable` error
 is returned when no correct `Accept` header is supplied.
 
+When an invalid `Accept` header is supplied, a `406 Not Acceptable` error is returned if the `:cascade`
+option is set to `false`. Otherwise a `404 Not Found` error is returned by Rack if no other route
+matches.
+
+### Accept-Version Header
+
+```ruby
+version 'v1', using: :accept_version_header
+```
+
+Using this versioning strategy, clients should pass the desired version in the HTTP `Accept-Version` header.
+
+    curl -H "Accept-Version:v1" http://localhost:9292/statuses/public_timeline
+
+By default, the first matching version is used when no `Accept-Version` 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 `406 Not Acceptable` error
+is returned when no correct `Accept` header is supplied.
+
 ### Param
 
 ```ruby
-version 'v1', :using => :param
+version 'v1', using: :param
 ```
 
 Using this versioning strategy, clients should pass the desired version as a request parameter,
@@ -218,7 +262,7 @@ either in the URL query string or in the request body.
 The default name for the query parameter is 'apiver' but can be specified using the `:parameter` option.
 
 ```ruby
-version 'v1', :using => :param, :parameter => "v"
+version 'v1', using: :param, parameter: "v"
 ```
 
     curl -H http://localhost:9292/statuses/public_timeline?v=v1
@@ -246,7 +290,7 @@ get :public_timeline do
 end
 ```
 
-Parameters are automatically populated from the request body on POST and PUT for form input, JSON and
+Parameters are automatically populated from the request body on `POST` and `PUT` for form input, JSON and
 XML content-types.
 
 The request:
@@ -259,7 +303,7 @@ The Grape endpoint:
 
 ```ruby
 post '/statuses' do
-  Status.create!({ :text => params[:text] })
+  Status.create!(text: params[:text])
 end
 ```
 
@@ -268,7 +312,7 @@ Multipart POSTs and PUTs are supported as well.
 The request:
 
 ```
-curl --form image_file=image.jpg http://localhost:9292/upload
+curl --form image_file=@image.jpg http://localhost:9292/upload
 ```
 
 The Grape endpoint:
@@ -279,6 +323,14 @@ post "upload" do
 end
 ```
 
+In the case of conflict between either of:
+
+* route string parameters
+* `GET`, `POST` and `PUT` parameters
+* the contents of the request body on `POST` and `PUT`
+
+route string parameters will have precedence.
+
 ## Parameter Validation and Coercion
 
 You can define validations and coercion options for your parameters using a `params` block.
@@ -290,6 +342,9 @@ params do
   group :media do
     requires :url
   end
+  optional :audio do
+    requires :format, type: Symbol, values: [:mp3, :wav, :aac, :ogg], default: :mp3
+  end
 end
 put ':id' do
   # params[:id] is an Integer
@@ -299,8 +354,57 @@ 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
-`params[:media][:url]` is required along with `params[:id]`.
+Optional parameters can have a default value.
+
+```ruby
+params do
+  optional :color, type: String, default: 'blue'
+  optional :random_number, type: Integer, default: -> { Random.rand(1..100) }
+  optional :non_random_number, type: Integer, default:  Random.rand(1..100)
+end
+```
+
+Parameters can be restricted to a specific set of values with the `:values` option.
+
+Default values are eagerly evaluated. Above `:non_random_number` will evaluate to the same
+number for each call to the endpoint of this `params` block. To have the default evaluate
+at calltime use a lambda, like `:random_number` above.
+
+```ruby
+params do
+  requires :status, type: Symbol, values: [:not_started, :processing, :done]
+end
+```
+
+The :values option can also be supplied with a `Proc` to be evalutated at runtime. For example, given a status
+model you may want to restrict by hashtags that you have previously defined in the `HashTag` model.
+
+```ruby
+params do
+  required :hashtag, type: String, values: -> { Hashtag.all.map(&:tag) }
+end
+```
+
+Parameters can be nested using `group` or by calling `requires` or `optional` with a block.
+In the above example, this means `params[:media][:url]` is required along with `params[:id]`,
+and `params[:audio][:format]` is required only if `params[:audio]` is present.
+With a block, `group`, `requires` and `optional` accept an additional option `type` which can
+be either `Array` or `Hash`, and defaults to `Array`. Depending on the value, the nested
+parameters will be treated either as values of a hash or as values of hashes in an array.
+
+```ruby
+params do
+  optional :preferences, type: Array do
+    requires :key
+    requires :value
+  end
+
+  requires :name, type: Hash do
+    requires :first_name
+    requires :last_name
+  end
+end
+```
 
 ### Namespace Validation and Coercion
 
@@ -326,13 +430,30 @@ end
 The `namespace` method has a number of aliases, including: `group`, `resource`,
 `resources`, and `segment`. Use whichever reads the best for your API.
 
+You can conveniently define a route parameter as a namespace using `route_param`.
+
+```ruby
+namespace :statuses do
+  route_param :id do
+    desc "Returns all replies for a status."
+    get 'replies' do
+      Status.find(params[:id]).replies
+    end
+    desc "Returns a status."
+    get do
+      Status.find(params[:id])
+    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"
+      raise Grape::Exceptions::Validation, param: @scope.full_name(attr_name), message: "must consist of alpha-numeric characters"
     end
   end
 end
@@ -340,7 +461,7 @@ end
 
 ```ruby
 params do
-  requires :text, :alpha_numeric => true
+  requires :text, alpha_numeric: true
 end
 ```
 
@@ -350,7 +471,7 @@ You can also create custom classes that take parameters.
 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 at the most #{@option} characters long"
+      raise Grape::Exceptions::Validation, param: @scope.full_name(attr_name), message: "must be at the most #{@option} characters long"
     end
   end
 end
@@ -358,26 +479,33 @@ end
 
 ```ruby
 params do
-  requires :text, :length => 140
+  requires :text, length: 140
 end
 ```
 
 ### Validation Errors
 
-When validation and coercion errors occur an exception of type `Grape::Exceptions::ValidationError` is raised.
+Validation and coercion errors are collected and an exception of type `Grape::Exceptions::ValidationErrors` is raised.
 If the exception goes uncaught it will respond with a status of 400 and an error message.
-You can rescue a `Grape::Exceptions::ValidationError` and respond with a custom response.
+You can rescue a `Grape::Exceptions::ValidationErrors` and respond with a custom response.
 
 ```ruby
-rescue_from Grape::Exceptions::ValidationError do |e|
+rescue_from Grape::Exceptions::ValidationErrors do |e|
     Rack::Response.new({
-        'status' => e.status,
-        'message' => e.message,
-        'param' => e.param
+      status: e.status,
+      message: e.message,
+      errors: e.errors
     }.to_json, e.status)
 end
 ```
 
+The validation errors are grouped by parameter name and can be accessed via ``Grape::Exceptions::ValidationErrors#errors``.
+
+### I18n
+
+Grape supports I18n for parameter-related error messages, but will fallback to English if
+translations for the default locale have not been provided. See [en.yml](lib/grape/locale/en.yml) for message keys.
+
 ## Headers
 
 Request headers are available through the `headers` helper or from `env` in their original form.
@@ -397,18 +525,32 @@ end
 You can set a response header with `header` inside an API.
 
 ```ruby
-header "X-Robots-Tag", "noindex"
+header 'X-Robots-Tag', 'noindex'
+```
+
+When raising `error!`, pass additional headers as arguments.
+
+```ruby
+error! 'Unauthorized', 401, 'X-Error-Detail' => 'Invalid token.'
 ```
 
 ## Routes
 
 Optionally, you can define requirements for your named route parameters using regular
-expressions. The route will match only if all requirements are met.
+expressions on namespace or endpoint. The route will match only if all requirements are met.
 
 ```ruby
-get ':id', :requirements => { :id => /[0-9]*/ } do
+get ':id', requirements: { id: /[0-9]*/ } do
   Status.find(params[:id])
 end
+
+namespace :outer, requirements: { id: /[0-9]*/ } do
+  get :id do
+  end
+
+  get ":id/edit" do
+  end
+end
 ```
 
 ## Helpers
@@ -441,23 +583,84 @@ class API < Grape::API
 end
 ```
 
+You can define reusable `params` using `helpers`.
+
+```ruby
+class API < Grape::API
+  helpers do
+    params :pagination do
+      optional :page, type: Integer
+      optional :per_page, type: Integer
+    end
+  end
+
+  desc "Get collection"
+  params do
+    use :pagination # aliases: includes, use_scope
+  end
+  get do
+    Collection.page(params[:page]).per(params[:per_page])
+  end
+end
+```
+
+You can also define reusable `params` using shared helpers.
+
+```ruby
+module SharedParams
+  extend Grape::API::Helpers
+
+  params :period do
+    optional :start_date
+    optional :end_date
+  end
+
+  params :pagination do
+    optional :page, type: Integer
+    optional :per_page, type: Integer
+  end
+end
+
+class API < Grape::API
+  helpers SharedParams
+
+  desc "Get collection"
+  params do
+    use :period, :pagination
+  end
+  get do
+    Collection.from(params[:start_date]).to(params[:end_date])
+              .page(params[:page]).per(params[:per_page])
+  end
+end
+```
+
+## Parameter Documentation
+
+You can attach additional documentation to `params` using a `documentation` hash.
+
+```ruby
+params do
+  optional :first_name, type: String, documentation: { example: 'Jim' }
+  requires :last_name, type: String, documentation: { example: 'Smith' }
+end
+```
+
 ## Cookies
 
 You can set, get and delete your cookies very simply using `cookies` method.
 
 ```ruby
 class API < Grape::API
-
   get 'status_count' do
     cookies[:status_count] ||= 0
     cookies[:status_count] += 1
-    { :status_count => cookies[:status_count] }
+    { status_count: cookies[:status_count] }
   end
 
   delete 'status_count' do
-    { :status_count => cookies.delete(:status_count) }
+    { status_count: cookies.delete(:status_count) }
   end
-
 end
 ```
 
@@ -465,10 +668,10 @@ Use a hash-based syntax to set more than one value.
 
 ```ruby
 cookies[:status_count] = {
-    :value => 0,
-    :expires => Time.tomorrow,
-    :domain => '.twitter.com',
-    :path => '/'
+  value: 0,
+  expires: Time.tomorrow,
+  domain: '.twitter.com',
+  path: '/'
 }
 
 cookies[:status_count][:value] +=1
@@ -483,7 +686,7 @@ cookies.delete :status_count
 Specify an optional path.
 
 ```ruby
-cookies.delete :status_count, :path => '/'
+cookies.delete :status_count, path: '/'
 ```
 
 ## Redirecting
@@ -491,11 +694,11 @@ cookies.delete :status_count, :path => '/'
 You can redirect to a new url temporarily (302) or permanently (301).
 
 ```ruby
-redirect "/statuses"
+redirect '/statuses'
 ```
 
 ```ruby
-redirect "/statuses", :permanent => true
+redirect '/statuses', permanent: true
 ```
 
 ## Allowed Methods
@@ -506,13 +709,11 @@ behavior with `do_not_route_head!`.
 
 ``` ruby
 class API < Grape::API
-
   do_not_route_head!
 
   get '/example' do
     # only responds to GET
   end
-
 end
 ```
 
@@ -522,19 +723,17 @@ include an "Allow" header listing the supported methods.
 
 ```ruby
 class API < Grape::API
-
   get '/rt_count' do
-    { :rt_count => current_user.rt_count }
+    { rt_count: current_user.rt_count }
   end
 
   params do
-    requires :value, :type => Integer, :desc => 'Value to add to the rt count.'
+    requires :value, type: Integer, desc: 'Value to add to the rt count.'
   end
   put '/rt_count' do
     current_user.rt_count += params[:value].to_i
-    { :rt_count => current_user.rt_count }
+    { rt_count: current_user.rt_count }
   end
-
 end
 ```
 
@@ -567,16 +766,43 @@ curl -X DELETE -v http://localhost:3000/rt_count/
 You can abort the execution of an API method by raising errors with `error!`.
 
 ```ruby
-error! "Access Denied", 401
+error! 'Access Denied', 401
 ```
 
 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
+error!({ error: "unexpected error", detail: "missing widget" }, 500)
 ```
 
+### Default Error HTTP Status Code
+
+By default Grape returns a 500 status code from `error!`. You can change this with `default_error_status`.
+
+``` ruby
+class API < Grape::API
+  default_error_status 400
+  get '/example' do
+    error! "This should have http status code 400"
+  end
+end
+```
+
+### Handling 404
+
+For Grape to handle all the 404s for your API, it can be useful to use a catch-all.
+In its simplest form, it can be like:
+
+```ruby
+route :any, '*path' do
+  error! # or something else
+end
+```
+
+It is very crucial to __define this endpoint at the very end of your API__, as it
+literally accepts every request.
+
 ## Exception Handling
 
 Grape can be told to rescue all exceptions and return them in the API format.
@@ -591,10 +817,12 @@ You can also rescue specific exceptions.
 
 ```ruby
 class Twitter::API < Grape::API
-  rescue_from ArgumentError, NotImplementedError
+  rescue_from ArgumentError, UserDefinedError
 end
 ```
 
+In this case ```UserDefinedError``` must be inherited from ```StandardError```.
+
 The error format will match the request format. See "Content-Types" below.
 
 Custom error formatters for existing and additional types can be defined with a proc.
@@ -621,13 +849,13 @@ class Twitter::API < Grape::API
 end
 ```
 
-You can rescue all exceptions with a code block. The `rack_response` wrapper
+You can rescue all exceptions with a code block. The `error_response` wrapper
 automatically sets the default error code and content-type.
 
 ```ruby
 class Twitter::API < Grape::API
   rescue_from :all do |e|
-    rack_response({ :message => "rescued from #{e.class.name}" })
+    error_response({ message: "rescued from #{e.class.name}" })
   end
 end
 ```
@@ -648,29 +876,68 @@ Or rescue specific exceptions.
 ```ruby
 class Twitter::API < Grape::API
   rescue_from ArgumentError do |e|
-    Rack::Response.new([ "ArgumentError: #{e.message}" ], 500)
+    Rack::Response.new([ "ArgumentError: #{e.message}" ], 500).finish
   end
   rescue_from NotImplementedError do |e|
-    Rack::Response.new([ "NotImplementedError: #{e.message}" ], 500)
+    Rack::Response.new([ "NotImplementedError: #{e.message}" ], 500).finish
   end
 end
 ```
 
+By default, `rescue_from` will rescue the exceptions listed and all their subclasses.
+
+Assume you have the following exception classes defined.
+
+```ruby
+module APIErrors
+  class ParentError < StandardError; end
+  class ChildError < ParentError; end
+end
+```
+
+Then the following `rescue_from` clause will rescue exceptions of type `APIErrors::ParentError` and its subclasses (in this case `APIErrors::ChildError`).
+
+```ruby
+rescue_from APIErrors::ParentError do |e|
+    Rack::Response.new({
+      error: "#{e.class} error",
+      message: e.message
+      }.to_json, e.status).finish
+end
+```
+
+To only rescue the base exception class, set `rescue_subclasses: false`.
+The code below will rescue exceptions of type `RuntimeError` but _not_ its subclasses.
+
+```ruby
+rescue_from RuntimeError, rescue_subclasses: false do |e|
+    Rack::Response.new(
+      status: e.status,
+      message: e.message,
+      errors: e.errors
+      }.to_json, e.status).finish
+end
+```
+
 #### Rails 3.x
 
-When mounted inside Rails 3.x, errors like "404 Not Found" or "406 Not Acceptable" will likely be
-handled and rendered by Rails handlers. For instance, accessing a nonexistent route "/api/foo"
-raises a 404, which inside rails will ultimately be translated to an `ActionController::RoutingError`,
-which most likely will get rendered to a HTML error page.
+When mounted inside containers, such as Rails 3.x, errors like "404 Not Found" or
+"406 Not Acceptable" will likely be handled and rendered by Rails handlers. For instance,
+accessing a nonexistent route "/api/foo" raises a 404, which inside rails will ultimately
+be translated to an `ActionController::RoutingError`, which most likely will get rendered
+to a HTML error page.
 
-Most APIs will enjoy avoiding Rails exceptions and have their own exceptions reaching the client.
-In that case, the `:cascade` option can be set to `false` on the versioning definition.
+Most APIs will enjoy preventing downstream handlers from handling errors. You may set the
+`:cascade` option to `false` for the entire API or separately on specific `version` definitions,
+which will remove the `X-Cascade: true` header from API responses.
 
 ```ruby
-version 'v1', :using => :header, :vendor => 'twitter', :cascade => false
+cascade false
 ```
 
-The `:cascade` option can also be used with the other versioning strategies (`:param` and `:path`).
+```ruby
+version 'v1', using: :header, vendor: 'twitter', cascade: false
+```
 
 ## Logging
 
@@ -722,9 +989,8 @@ By default, Grape supports _XML_, _JSON_, and _TXT_ content-types. The default f
 
 Serialization takes place automatically. For example, you do not have to call `to_json` in each JSON API implementation.
 
-Your API can declare which types to support by using `content_type`. Response format
-is determined by the request's extension, an explicit `format` parameter in the query
-string, or `Accept` header.
+Your API can declare which types to support by using `content_type`. Response format is determined by the
+request's extension, an explicit `format` parameter in the query string, or `Accept` header.
 
 The following API will only respond to the JSON content-type and will not parse any other input than `application/json`,
 `application/x-www-form-urlencoded`, `multipart/form-data`, `multipart/related` and `multipart/mixed`. All other requests
@@ -736,6 +1002,16 @@ class Twitter::API < Grape::API
 end
 ```
 
+When the content-type is omitted, Grape will return a 406 error code unless `default_format` is specified.
+The following API will try to parse any data without a content-type using a JSON parser.
+
+```ruby
+class Twitter::API < Grape::API
+  format :json
+  default_format :json
+end
+```
+
 If you combine `format` with `rescue_from :all`, errors will be rendered using the same format.
 If you do not want this behavior, set the default error formatter with `default_error_formatter`.
 
@@ -773,7 +1049,7 @@ end
 
 Built-in formats are the following.
 
-* `:json`: use object's `to_json` when available, otherwise call `MultiJson.dump`
+* `:json` and `:jsonapi`: use object's `to_json` when available, otherwise call `MultiJson.dump`
 * `:xml`: use object's `to_xml` when available, usually via `MultiXml`, otherwise call `to_s`
 * `:txt`: use object's `to_txt` when available, otherwise `to_s`
 * `:serializable_hash`: use object's `serializable_hash` when available, otherwise fallback to `:json`
@@ -796,6 +1072,43 @@ The order for choosing the format is the following.
 * Use the default format, if specified by the `default_format` option.
 * Default to `:txt`.
 
+### JSONP
+
+Grape supports JSONP via [Rack::JSONP](https://github.com/rack/rack-contrib), part of the
+[rack-contrib](https://github.com/rack/rack-contrib) gem. Add `rack-contrib` to your `Gemfile`.
+
+```ruby
+require 'rack/contrib'
+
+class API < Grape::API
+  use Rack::JSONP
+  format :json
+  get '/' do
+    'Hello World'
+  end
+end
+```
+
+### CORS
+
+Grape supports CORS via [Rack::CORS](https://github.com/cyu/rack-cors), part of the
+[rack-cors](https://github.com/cyu/rack-cors) gem. Add `rack-cors` to your `Gemfile`,
+then use the middleware in your config.ru file.
+
+```ruby
+require 'rack/cors'
+
+use Rack::Cors do
+  allow do
+    origins '*'
+    resource '*', headers: :any, methods: :get
+  end
+end
+
+run Twitter::API
+
+```
+
 ## Content-type
 
 Content-type is set by the formatter. You can override the content-type of the response at runtime
@@ -817,7 +1130,8 @@ section above. It also supports custom data formats. You must declare additional
 `content_type` and optionally supply a parser via `parser` unless a parser is already available within
 Grape to enable a custom format. Such a parser can be a function or a class.
 
-Without a parser, data is available "as-is" and can be read with `env['rack.input'].read`.
+With a parser, parsed data is available "as-is" in `env['api.request.body']`.
+Without a parser, data is available "as-is" and in `env['api.request.input']`.
 
 The following example is a trivial parser that will assign any input with the "text/custom" content-type
 to `:value`. The parameter will be available via `params[:value]` inside the API call.
@@ -825,7 +1139,7 @@ to `:value`. The parameter will be available via `params[:value]` inside the API
 ```ruby
 module CustomParser
   def self.call(object, env)
-    { :value => object.to_s }
+    { value: object.to_s }
   end
 end
 ```
@@ -846,6 +1160,8 @@ You can invoke the above API as follows.
 curl -X PUT -d 'data' 'http://localhost:9292/value' -H Content-Type:text/custom -v
 ```
 
+You can disable parsing for a content-type with `nil`. For example, `parser :json, nil` will disable JSON parsing altogether. The request data is then available as-is in `env['api.request.body']`.
+
 ## RESTful Model Representations
 
 Grape supports a range of ways to present your data with some help from a generic `present` method,
@@ -854,23 +1170,22 @@ hash may include `:with`, which defines the entity to expose.
 
 ### Grape Entities
 
-Add the [grape-entity](https://github.com/agileanimal/grape-entity) gem to your Gemfile.
-Please refer to the [grape-entity documentation](https://github.com/agileanimal/grape-entity/blob/master/README.markdown)
+Add the [grape-entity](https://github.com/intridea/grape-entity) gem to your Gemfile.
+Please refer to the [grape-entity documentation](https://github.com/intridea/grape-entity/blob/master/README.md)
 for more details.
 
 The following example exposes statuses.
 
 ```ruby
 module API
-
   module Entities
     class Status < Grape::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 :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(status.txt) }
-      expose :replies, :using => API::Status, :as => :replies
+      expose :replies, using: API::Status, as: :replies
     end
   end
 
@@ -878,24 +1193,62 @@ module API
     version 'v1'
 
     desc 'Statuses index', {
-      :object_fields => API::Entities::Status.documentation
+      params: API::Entities::Status.documentation
     }
     get '/statuses' do
       statuses = Status.all
       type = current_user.admin? ? :full : :default
-      present statuses, with: API::Entities::Status, :type => type
+      present statuses, with: API::Entities::Status, type: type
     end
   end
 end
 ```
 
+You can use entity documentation directly in the params block with `using: Entity.documentation`.
+
+```ruby
+module API
+  class Statuses < Grape::API
+    version 'v1'
+
+    desc 'Create a status', {
+      requires :all, except: [:ip], using: API::Entities::Status.documentation.except(:id)
+    }
+    post '/status' do
+      Status.create! params
+    end
+  end
+end
+```
+
+You can present with multiple entities using an optional Symbol argument.
+
+```ruby
+  get '/statuses' do
+    statuses = Status.all.page(1).per(20)
+    present :total_page, 10
+    present :per_page, 20
+    present :statuses, statuses, with: API::Entities::Status
+  end
+```
+
+The response will be
+
+```
+  {
+    total_page: 10,
+    per_page: 20,
+    statuses: []
+  }
+```
+
 In addition to separately organizing entities, it may be useful to put them as namespaced
 classes underneath the model they represent.
 
 ```ruby
 class Status
   def entity
-    Status.new(self)
+    Entity.new(self)
   end
 
   class Entity < Grape::Entity
@@ -922,6 +1275,13 @@ You can use [Rabl](https://github.com/nesquena/rabl) templates with the help of
 [grape-rabl](https://github.com/LTe/grape-rabl) gem, which defines a custom Grape Rabl
 formatter.
 
+### Active Model Serializers
+
+You can use [Active Model Serializers](https://github.com/rails-api/active_model_serializers) serializers with the help of the
+[grape-active_model_serializers](https://github.com/jrhe/grape-active_model_serializers) gem, which defines a custom Grape AMS
+formatter.
+
+
 ## Authentication
 
 ### Basic and Digest Auth
@@ -936,7 +1296,7 @@ end
 ```
 
 ```ruby
-http_digest({ :realm => 'Test Api', :opaque => 'app secret' }) do |username|
+http_digest({ realm: 'Test Api', opaque: 'app secret' }) do |username|
   # lookup the user's password here
   { 'user1' => 'password1' }[username]
 end
@@ -971,7 +1331,7 @@ call with `route`.
 class MyAPI < Grape::API
   desc "Returns a description of a parameter."
   params do
-    requires :id, :type => Integer, :desc => "Identity."
+    requires :id, type: Integer, desc: "Identity."
   end
   get "params/:id" do
     route.route_params[params[:id]] # yields the parameter description
@@ -996,7 +1356,21 @@ end
 
 ## Before and After
 
-Execute a block before or after every API call with `before` and `after`.
+Blocks can be executed before or after every API call, using `before`, `after`,
+`before_validation` and `after_validation`.
+
+Before and after callbacks execute in the following order:
+
+1. `before`
+2. `before_validation`
+3. _validations_
+4. `after_validation`
+5. _the API call_
+6. `after`
+
+Steps 4, 5 and 6 only happen if validation succeeds.
+
+E.g. using `before`:
 
 ```ruby
 before do
@@ -1004,6 +1378,68 @@ before do
 end
 ```
 
+The block applies to every API call within and below the current namespace:
+
+```ruby
+class MyAPI < Grape::API
+  get '/' do
+    "root - #{@blah}"
+  end
+
+  namespace :foo do
+    before do
+      @blah = 'blah'
+    end
+
+    get '/' do
+      "root - foo - #{@blah}"
+    end
+
+    namespace :bar do
+      get '/' do
+        "root - foo - bar - #{@blah}"
+      end
+    end
+  end
+end
+```
+
+The behaviour is then:
+
+```bash
+GET /           # 'root - '
+GET /foo        # 'root - foo - blah'
+GET /foo/bar    # 'root - foo - bar - blah'
+```
+
+Params on a `namespace` (or whatever alias you are using) also work when using
+`before_validation` or `after_validation`:
+
+```ruby
+class MyAPI < Grape::API
+  params do
+    requires :blah, type: Integer
+  end
+  resource ':blah' do
+    after_validation do
+      # if we reach this point validations will have passed
+      @blah = declared(params, include_missing: false)[:blah]
+    end
+
+    get '/' do
+      @blah.class
+    end
+  end
+end
+```
+
+The behaviour is then:
+
+```bash
+GET /123        # 'Fixnum'
+GET /foo        # 400 error - 'blah is invalid'
+```
+
 ## Anchoring
 
 Grape by default anchors all request paths, which means that the request URL
@@ -1011,7 +1447,7 @@ 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 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.
+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:
@@ -1019,7 +1455,7 @@ For instance when you're API needs to get part of an URL, for instance:
 ```ruby
 class TwitterAPI < Grape::API
   namespace :statuses do
-    get '/(*:status)', :anchor => false do
+    get '/(*:status)', anchor: false do
 
     end
   end
@@ -1093,13 +1529,13 @@ describe Twitter::API do
 end
 ```
 
-In Rails, HTTP request tests would go into the `spec/request` group. You may want your API code to go into
+In Rails, HTTP request tests would go into the `spec/requests` 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/
+  config.include RSpec::Rails::RequestExampleGroup, type: :request, example_group: {
+    file_path: /spec\/api/
   }
 end
 ```
@@ -1112,15 +1548,17 @@ Add API paths to `config/application.rb`.
 
 ```ruby
 # Auto-load API and its subdirectories
-config.paths.add "app/api", :glob => "**/*.rb"
-config.autoload_paths += Dir["#{Rails.root}/app/api/*"]
+config.paths.add File.join("app", "api"), glob: File.join("**", "*.rb")
+config.autoload_paths += Dir[Rails.root.join("app", "api", "*")]
 ```
 
 Create `config/initializers/reload_api.rb`.
 
 ```ruby
 if Rails.env.development?
-  api_files = Dir["#{Rails.root}/app/api/**/*.rb"]
+  ActiveSupport::Dependencies.explicitly_unloadable_constants << "Twitter::API"
+
+  api_files = Dir[Rails.root.join('app', 'api', '**', '*.rb')]
   api_reloader = ActiveSupport::FileUpdateChecker.new(api_files) do
     Rails.application.reload_routes!
   end
@@ -1132,21 +1570,18 @@ end
 
 See [StackOverflow #3282655](http://stackoverflow.com/questions/3282655/ruby-on-rails-3-reload-lib-directory-for-each-request/4368838#4368838) for more information.
 
-
 ## Performance Monitoring
 
-Grape integrates with NewRelic via the [newrelic-grape](https://github.com/flyerhzm/newrelic-grape) gem.
+Grape integrates with NewRelic via the
+[newrelic-grape](https://github.com/flyerhzm/newrelic-grape) gem, and
+with Librato Metrics with the [grape-librato](https://github.com/seanmoon/grape-librato) gem.
 
 ## Contributing to Grape
 
-Grape is work of dozens of contributors. You're encouraged to submit pull requests, propose
+Grape is work of hundreds 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
-* Add a line to `CHANGELOG.markdown` describing your change
-* Commit, push and make a pull request. Bonus points for topic branches.
+See [CONTRIBUTING](CONTRIBUTING.md).
 
 ## License
 
@@ -1154,4 +1589,4 @@ MIT License. See LICENSE for details.
 
 ## Copyright
 
-Copyright (c) 2010-2012 Michael Bleigh, and Intridea, Inc.
+Copyright (c) 2010-2013 Michael Bleigh, and Intridea, Inc.