grape 0.12.0 → 0.14.0

data/README.md

@@ -1,10 +1,10 @@
 ![grape logo](grape.png)
 
-[![Gem Version](http://img.shields.io/gem/v/grape.svg)](http://badge.fury.io/rb/grape)
-[![Build Status](http://img.shields.io/travis/intridea/grape.svg)](https://travis-ci.org/intridea/grape)
-[![Dependency Status](https://gemnasium.com/intridea/grape.svg)](https://gemnasium.com/intridea/grape)
-[![Code Climate](https://codeclimate.com/github/intridea/grape.svg)](https://codeclimate.com/github/intridea/grape)
-[![Inline docs](http://inch-ci.org/github/intridea/grape.svg)](http://inch-ci.org/github/intridea/grape)
+[![Gem Version](https://badge.fury.io/rb/grape.svg)](http://badge.fury.io/rb/grape)
+[![Build Status](https://travis-ci.org/ruby-grape/grape.svg?branch=master)](https://travis-ci.org/ruby-grape/grape)
+[![Dependency Status](https://gemnasium.com/ruby-grape/grape.svg)](https://gemnasium.com/ruby-grape/grape)
+[![Code Climate](https://codeclimate.com/github/ruby-grape/grape.svg)](https://codeclimate.com/github/ruby-grape/grape)
+[![Inline docs](http://inch-ci.org/github/ruby-grape/grape.svg)](http://inch-ci.org/github/ruby-grape/grape)
 
 ## Table of Contents
 
@@ -29,6 +29,13 @@
   - [Declared](#declared)
   - [Include Missing](#include-missing)
 - [Parameter Validation and Coercion](#parameter-validation-and-coercion)
+  - [Supported Parameter Types](#supported-parameter-types)
+  - [Custom Types and Coercions](#custom-types-and-coercions)
+  - [Multipart File Parameters](#multipart-file-parameters)
+  - [First-Class `JSON` Types](#first-class-json-types)
+  - [Multiple Allowed Types](#multiple-allowed-types)
+  - [Validation of Nested Parameters](#validation-of-nested-parameters)
+  - [Dependent Parameters](#dependent-parameters)
   - [Built-in Validators](#built-in-validators)
   - [Namespace Validation and Coercion](#namespace-validation-and-coercion)
   - [Custom Validators](#custom-validators)
@@ -37,6 +44,7 @@
 - [Headers](#headers)
 - [Routes](#routes)
 - [Helpers](#helpers)
+- [Path Helpers](#path-helpers)
 - [Parameter Documentation](#parameter-documentation)
 - [Cookies](#cookies)
 - [HTTP Status Code](#http-status-code)
@@ -55,7 +63,7 @@
 - [API Data Formats](#api-data-formats)
 - [RESTful Model Representations](#restful-model-representations)
   - [Grape Entities](#grape-entities)
-  - [Hypermedia](#hypermedia)
+  - [Hypermedia and Roar](#hypermedia-and-roar)
   - [Rabl](#rabl)
   - [Active Model Serializers](#active-model-serializers)
 - [Sending Raw or No Data](#sending-raw-or-no-data)
@@ -66,7 +74,7 @@
 - [Anchoring](#anchoring)
 - [Using Custom Middleware](#using-custom-middleware)
   - [Rails Middleware](#rails-middleware)
-    - [Remote IP](#remote-ip)
+  - [Remote IP](#remote-ip)
 - [Writing Tests](#writing-tests)
   - [Writing Tests with Rack](#writing-tests-with-rack)
   - [Writing Tests with Rails](#writing-tests-with-rails)
@@ -75,8 +83,9 @@
   - [Reloading in Rack Applications](#reloading-in-rack-applications)
   - [Reloading in Rails Applications](#reloading-in-rails-applications)
 - [Performance Monitoring](#performance-monitoring)
+  - [Active Support Instrumentation](#active-support-instrumentation)
+  - [Monitoring Products](#monitoring-products)
 - [Contributing to Grape](#contributing-to-grape)
-- [Hacking on Grape](#hacking-on-grape)
 - [License](#license)
 - [Copyright](#copyright)
 
@@ -90,13 +99,13 @@ content negotiation, versioning and much more.
 
 ## Stable Release
 
-You're reading the documentation for the stable release of Grape 0.12.0.
+You're reading the documentation for the stable release of Grae [0.14.0](https://github.com/ruby-grape/grape/blob/v0.14.0/README.md).
 Please read [UPGRADING](UPGRADING.md) when upgrading from a previous version.
 
 ## Project Resources
 
+* [Grape Website](http://www.ruby-grape.org)
 * Need help? [Grape Google Group](http://groups.google.com/group/ruby-grape)
-* [Grape Wiki](https://github.com/intridea/grape/wiki)
 
 ## Installation
 
@@ -134,20 +143,20 @@ module Twitter
     end
 
     resource :statuses do
-      desc "Return a public timeline."
+      desc 'Return a public timeline.'
       get :public_timeline do
         Status.limit(20)
       end
 
-      desc "Return a personal timeline."
+      desc 'Return a personal timeline.'
       get :home_timeline do
         authenticate!
         current_user.statuses.limit(20)
       end
 
-      desc "Return a status."
+      desc 'Return a status.'
       params do
-        requires :id, type: Integer, desc: "Status id."
+        requires :id, type: Integer, desc: 'Status id.'
       end
       route_param :id do
         get do
@@ -155,9 +164,9 @@ module Twitter
         end
       end
 
-      desc "Create a status."
+      desc 'Create a status.'
       params do
-        requires :status, type: String, desc: "Your status."
+        requires :status, type: String, desc: 'Your status.'
       end
       post do
         authenticate!
@@ -167,10 +176,10 @@ module Twitter
         })
       end
 
-      desc "Update a status."
+      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!
@@ -180,9 +189,9 @@ module Twitter
         })
       end
 
-      desc "Delete a status."
+      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!
@@ -242,13 +251,13 @@ require 'grape'
 
 class API < Grape::API
   get :hello do
-    { hello: "world" }
+    { hello: 'world' }
   end
 end
 
 class Web < Sinatra::Base
   get '/' do
-    "Hello world."
+    'Hello world.'
   end
 end
 
@@ -277,7 +286,7 @@ Additionally, if the version of your Rails is 4.0+ and the application uses the
 
 ```ruby
 # Gemfile
-gem "hashie-forbidden_attributes"
+gem 'hashie-forbidden_attributes'
 ```
 
 See [below](#reloading-api-changes-in-development) for additional code that enables reloading of API changes in development.
@@ -323,6 +332,14 @@ Using this versioning strategy, clients should pass the desired version in the U
 version 'v1', using: :header, vendor: 'twitter'
 ```
 
+Currently, Grape only supports versioned media types in the following format:
+
+```
+vnd.vendor-and-or-resource-v1234+format
+```
+
+Basically all tokens between the final `-` and the `+` will be interpreted as the version.
+
 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
@@ -336,29 +353,6 @@ When an invalid `Accept` header is supplied, a `406 Not Acceptable` error is ret
 option is set to `false`. Otherwise a `404 Not Found` error is returned by Rack if no other route
 matches.
 
-### HTTP Status Code
-
-By default Grape returns a 200 status code for `GET`-Requests and 201 for `POST`-Requests.
-You can use `status` to query and set the actual HTTP Status Code
-
-```ruby
-post do
-  status 202
-
-  if status == 200
-     # do some thing
-  end
-end
-```
-
-You can also use one of status codes symbols that are provided by [Rack utils](http://www.rubydoc.info/github/rack/rack/Rack/Utils#HTTP_STATUS_CODES-constant)
-
-```ruby
-post do
-  status :no_content
-end
-```
-
 ### Accept-Version Header
 
 ```ruby
@@ -388,7 +382,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 http://localhost:9292/statuses/public_timeline?v=v1
@@ -399,21 +393,21 @@ version 'v1', using: :param, parameter: "v"
 You can add a description to API methods and namespaces.
 
 ```ruby
-desc "Returns your public timeline." do
+desc 'Returns your public timeline.' do
   detail 'more details'
   params  API::Entities::Status.documentation
   success API::Entities::Entity
-  failure [[401, 'Unauthorized', "Entities::Error"]]
+  failure [[401, 'Unauthorized', 'Entities::Error']]
   named 'My named route'
-  headers [XAuthToken: {
-             description: 'Valdates your identity',
-             required: true
-           },
-           XOptionalHeader: {
-             description: 'Not really needed',
+  headers XAuthToken: {
+            description: 'Valdates your identity',
+            required: true
+          },
+          XOptionalHeader: {
+            description: 'Not really needed',
             required: false
-           }
-          ]
+          }
+
 end
 get :public_timeline do
   Status.limit(20)
@@ -466,7 +460,7 @@ curl --form image_file='@image.jpg;type=image/jpg' http://localhost:9292/upload
 The Grape endpoint:
 
 ```ruby
-post "upload" do
+post 'upload' do
   # file in params[:image_file]
 end
 ```
@@ -479,19 +473,19 @@ In the case of conflict between either of:
 
 route string parameters will have precedence.
 
-#### Declared
+### Declared
 
-Grape allows you to access only the parameters that have been declared by your `params` block. It filters out the params that have been passed, but are not allowed. Let's have the following api:
+Grape allows you to access only the parameters that have been declared by your `params` block. It filters out the params that have been passed, but are not allowed. Consider the following API endpoint:
 
 ````ruby
 format :json
 
 post 'users/signup' do
-  { "declared_params" => declared(params) }
+  { 'declared_params' => declared(params) }
 end
 ````
 
-If we do not specify any params, declared will return an empty Hashie::Mash instance.
+If we do not specify any params, `declared` will return an empty `Hashie::Mash` instance.
 
 **Request**
 
@@ -521,7 +515,7 @@ params do
 end
 
 post 'users/signup' do
-  { "declared_params" => declared(params) }
+  { 'declared_params' => declared(params) }
 end
 ````
 
@@ -544,15 +538,19 @@ curl -X POST -H "Content-Type: application/json" localhost:9292/users/signup -d
 }
 ````
 
-Returned hash is a Hashie::Mash instance so you can access parameters via dot notation:
+The returned hash is a `Hashie::Mash` instance, allowing you to access parameters via dot notation:
 
 ```ruby
-  declared(params).user == declared(params)["user"]
+  declared(params).user == declared(params)['user']
 ```
 
-#### Include missing
 
-By default `declared(params)` returns parameters that has `nil` value. If you want to return only the parameters that have any value, you can use the `include_missing` option. By default it is `true`. Let's have the following api:
+The `#declared` method is not available to `before` filters, as those are evaluated prior
+to parameter coercion.
+
+### Include missing
+
+By default `declared(params)` includes parameters that have `nil` values. If you want to return only the parameters that are not `nil`, you can use the `include_missing` option. By default, `include_missing` is set to `true`. Consider the following API:
 
 ````ruby
 format :json
@@ -563,7 +561,7 @@ params do
 end
 
 post 'users/signup' do
-  { "declared_params" => declared(params, include_missing: false) }
+  { 'declared_params' => declared(params, include_missing: false) }
 end
 ````
 
@@ -613,7 +611,7 @@ params do
 end
 
 post 'users/signup' do
-  { "declared_params" => declared(params, include_missing: false) }
+  { 'declared_params' => declared(params, include_missing: false) }
 end
 ````
 
@@ -685,7 +683,7 @@ You can define validations and coercion options for your parameters using a `par
 ```ruby
 params do
   requires :id, type: Integer
-  optional :text, type: String, regexp: /^[a-z]+$/
+  optional :text, type: String, regexp: /\A[a-z]+\z/
   group :media do
     requires :url
   end
@@ -729,7 +727,167 @@ params do
 end
 ```
 
-#### Validation of Nested Parameters
+### Supported Parameter Types
+
+The following are all valid types, supported out of the box by Grape:
+
+* Integer
+* Float
+* BigDecimal
+* Numeric
+* Date
+* DateTime
+* Time
+* Boolean
+* String
+* Symbol
+* Rack::Multipart::UploadedFile (alias `File`)
+* JSON
+
+### Custom Types and Coercions
+
+Aside from the default set of supported types listed above, any class can be
+used as a type so long as an explicit coercion method is supplied. If the type
+implements a class-level `parse` method, Grape will use it automatically.
+This method must take one string argument and return an instance of the correct
+type, or raise an exception to indicate the value was invalid. E.g.,
+
+```ruby
+class Color
+  attr_reader :value
+  def initialize(color)
+    @value = color
+  end
+
+  def self.parse(value)
+    fail 'Invalid color' unless %w(blue red green).include?(value)
+    new(value)
+  end
+end
+
+# ...
+
+params do
+  requires :color, type: Color, default: Color.new('blue')
+end
+
+get '/stuff' do
+  # params[:color] is already a Color.
+  params[:color].value
+end
+```
+
+Alternatively, a custom coercion method may be supplied for any type of parameter
+using `coerce_with`. Any class or object may be given that implements a `parse` or
+`call` method, in that order of precedence. The method must accept a single string
+parameter, and the return value must match the given `type`.
+
+```ruby
+params do
+  requires :passwd, type: String, coerce_with: Base64.method(:decode)
+  requires :loud_color, type: Color, coerce_with: ->(c) { Color.parse(c.downcase) }
+
+  requires :obj, type: Hash, coerce_with: JSON do
+    requires :words, type: Array[String], coerce_with: ->(val) { val.split(/\s+/) }
+    optional :time, type: Time, coerce_with: Chronic
+  end
+end
+```
+
+### Multipart File Parameters
+
+Grape makes use of `Rack::Request`'s built-in support for multipart
+file parameters. Such parameters can be declared with `type: File`:
+
+```ruby
+params do
+  requires :avatar, type: File
+end
+post '/' do
+  # Parameter will be wrapped using Hashie:
+  params.avatar.filename # => 'avatar.png'
+  params.avatar.type     # => 'image/png'
+  params.avatar.tempfile # => #<File>
+end
+```
+
+### First-Class `JSON` Types
+
+Grape supports complex parameters given as JSON-formatted strings using the special `type: JSON`
+declaration. JSON objects and arrays of objects are accepted equally, with nested validation
+rules applied to all objects in either case:
+
+```ruby
+params do
+  requires :json, type: JSON do
+    requires :int, type: Integer, values: [1, 2, 3]
+  end
+end
+get '/' do
+  params[:json].inspect
+end
+
+# ...
+
+client.get('/', json: '{"int":1}') # => "{:int=>1}"
+client.get('/', json: '[{"int":"1"}]') # => "[{:int=>1}]"
+
+client.get('/', json: '{"int":4}') # => HTTP 400
+client.get('/', json: '[{"int":4}]') # => HTTP 400
+```
+
+Additionally `type: Array[JSON]` may be used, which explicitly marks the parameter as an array
+of objects. If a single object is supplied it will be wrapped.
+
+```ruby
+params do
+  requires :json, type: Array[JSON] do
+    requires :int, type: Integer
+  end
+end
+get '/' do
+  params[:json].each { |obj| ... } # always works
+end
+```
+For stricter control over the type of JSON structure which may be supplied,
+use `type: Array, coerce_with: JSON` or `type: Hash, coerce_with: JSON`.
+
+### Multiple Allowed Types
+
+Variant-type parameters can be declared using the `types` option rather than `type`:
+
+```ruby
+params do
+  requires :status_code, types: [Integer, String, Array[Integer, String]]
+end
+get '/' do
+  params[:status_code].inspect
+end
+
+# ...
+
+client.get('/', status_code: 'OK_GOOD') # => "OK_GOOD"
+client.get('/', status_code: 300) # => 300
+client.get('/', status_code: %w(404 NOT FOUND)) # => [404, "NOT", "FOUND"]
+```
+
+As a special case, variant-member-type collections may also be declared, by
+passing a `Set` or `Array` with more than one member to `type`:
+
+```ruby
+params do
+  requires :status_codes, type: Array[Integer,String]
+end
+get '/' do
+  params[:status_codes].inspect
+end
+
+# ...
+
+client.get('/', status_codes: %w(1 two)) # => [1, "two"]
+```
+
+### Validation of Nested Parameters
 
 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]`,
@@ -752,6 +910,21 @@ params do
 end
 ```
 
+### Dependent Parameters
+
+Suppose some of your parameters are only relevant if another parameter is given;
+Grape allows you to express this relationship through the `given` method in your
+parameters block, like so:
+
+```ruby
+params do
+  optional :shelf_id, type: Integer
+  given :shelf_id do
+    requires :bin_id, type: Integer
+  end
+end
+```
+
 ### Built-in Validators
 
 #### `allow_blank`
@@ -939,14 +1112,14 @@ Namespaces allow parameter definitions and apply to every method within the name
 ```ruby
 namespace :statuses do
   params do
-    requires :user_id, type: Integer, desc: "A user ID."
+    requires :user_id, type: Integer, desc: 'A user ID.'
   end
-  namespace ":user_id" do
+  namespace ':user_id' do
     desc "Retrieve a user's status."
     params do
-      requires :status_id, type: Integer, desc: "A status ID."
+      requires :status_id, type: Integer, desc: 'A status ID.'
     end
-    get ":status_id" do
+    get ':status_id' do
       User.find(params[:user_id]).statuses.find(params[:status_id])
     end
   end
@@ -961,11 +1134,11 @@ 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."
+    desc 'Returns all replies for a status.'
     get 'replies' do
       Status.find(params[:id]).replies
     end
-    desc "Returns a status."
+    desc 'Returns a status.'
     get do
       Status.find(params[:id])
     end
@@ -978,8 +1151,8 @@ end
 ```ruby
 class AlphaNumeric < Grape::Validations::Base
   def validate_param!(attr_name, params)
-    unless params[attr_name] =~ /^[[:alnum:]]+$/
-      fail Grape::Exceptions::Validation, params: [@scope.full_name(attr_name)], message: "must consist of alpha-numeric characters"
+    unless params[attr_name] =~ /\A[[:alnum:]]+\z/
+      fail Grape::Exceptions::Validation, params: [@scope.full_name(attr_name)], message: 'must consist of alpha-numeric characters'
     end
   end
 end
@@ -1034,6 +1207,16 @@ subject.rescue_from Grape::Exceptions::ValidationErrors do |e|
 end
 ```
 
+`Grape::Exceptions::ValidationErrors#full_messages` returns the validation messages as an array. `Grape::Exceptions::ValidationErrors#message` joins the messages to one string.
+
+For responding with an array of validation messages, you can use `Grape::Exceptions::ValidationErrors#full_messages`.
+```ruby
+format :json
+subject.rescue_from Grape::Exceptions::ValidationErrors do |e|
+  error!({ messages: e.full_messages }, 400)
+end
+```
+
 ### I18n
 
 Grape supports I18n for parameter-related error messages, but will fallback to English if
@@ -1081,7 +1264,7 @@ namespace :outer, requirements: { id: /[0-9]*/ } do
   get :id do
   end
 
-  get ":id/edit" do
+  get ':id/edit' do
   end
 end
 ```
@@ -1127,7 +1310,7 @@ class API < Grape::API
     end
   end
 
-  desc "Get collection"
+  desc 'Get collection'
   params do
     use :pagination # aliases: includes, use_scope
   end
@@ -1157,7 +1340,7 @@ end
 class API < Grape::API
   helpers SharedParams
 
-  desc "Get collection."
+  desc 'Get collection.'
   params do
     use :period, :pagination
   end
@@ -1187,7 +1370,7 @@ end
 class API < Grape::API
   helpers SharedParams
 
-  desc "Get a sorted collection."
+  desc 'Get a sorted collection.'
   params do
     use :order, order_by:%i(id created_at), default_order_by: :created_at, default_order: :asc
   end
@@ -1198,6 +1381,10 @@ class API < Grape::API
 end
 ```
 
+## Path Helpers
+
+If you need methods for generating paths inside your endpoints, please see the [grape-route-helpers](https://github.com/reprah/grape-route-helpers) gem.
+
 ## Parameter Documentation
 
 You can attach additional documentation to `params` using a `documentation` hash.
@@ -1252,6 +1439,29 @@ Specify an optional path.
 cookies.delete :status_count, path: '/'
 ```
 
+## HTTP Status Code
+
+By default Grape returns a 200 status code for `GET`-Requests and 201 for `POST`-Requests.
+You can use `status` to query and set the actual HTTP Status Code
+
+```ruby
+post do
+  status 202
+
+  if status == 200
+     # do some thing
+  end
+end
+```
+
+You can also use one of status codes symbols that are provided by [Rack utils](http://www.rubydoc.info/github/rack/rack/Rack/Utils#HTTP_STATUS_CODES-constant)
+
+```ruby
+post do
+  status :no_content
+end
+```
+
 ## Redirecting
 
 You can redirect to a new url temporarily (302) or permanently (301).
@@ -1336,10 +1546,10 @@ 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)
 ```
 
-You can present documented errors with a Grape entity using the the [grape-entity](https://github.com/intridea/grape-entity) gem.
+You can present documented errors with a Grape entity using the the [grape-entity](https://github.com/ruby-grape/grape-entity) gem.
 
 ```ruby
 module API
@@ -1376,7 +1586,7 @@ By default Grape returns a 500 status code from `error!`. You can change this wi
 class API < Grape::API
   default_error_status 400
   get '/example' do
-    error! "This should have http status code 400"
+    error! 'This should have http status code 400'
   end
 end
 ```
@@ -1421,7 +1631,7 @@ Custom error formatters for existing and additional types can be defined with a
 
 ```ruby
 class Twitter::API < Grape::API
-  error_formatter :txt, lambda { |message, backtrace, options, env|
+  error_formatter :txt, ->(message, backtrace, options, env) {
     "error: #{message} from #{backtrace}"
   }
 end
@@ -1441,8 +1651,7 @@ class Twitter::API < Grape::API
 end
 ```
 
-You can rescue all exceptions with a code block. The `error!` wrapper
-automatically sets the default error code and content-type.
+You can rescue all exceptions with a code block. The `error!` wrapper automatically sets the default error code and content-type.
 
 ```ruby
 class Twitter::API < Grape::API
@@ -1458,19 +1667,17 @@ Optionally, you can set the format, status code and headers.
 class Twitter::API < Grape::API
   format :json
   rescue_from :all do |e|
-    error!({ error: "Server error.", 500, { 'Content-Type' => 'text/error' } })
+    error!({ error: 'Server error.' }, 500, { 'Content-Type' => 'text/error' })
   end
 end
 ```
 
-
-You can also rescue specific exceptions with a code block and handle the Rack
-response at the lowest level.
+You can also rescue specific exceptions with a code block and handle the Rack response at the lowest level.
 
 ```ruby
 class Twitter::API < Grape::API
   rescue_from :all do |e|
-    Rack::Response.new([ e.message ], 500, { "Content-type" => "text/error" }).finish
+    Rack::Response.new([ e.message ], 500, { 'Content-type' => 'text/error' }).finish
   end
 end
 ```
@@ -1524,9 +1731,15 @@ rescue_from RuntimeError, rescue_subclasses: false do |e|
 end
 ```
 
-#### Rails 3.x
+The `rescue_from` block must return a `Rack::Response` object, call `error!` or re-raise an exception.
+
+#### Unrescuable Exceptions
 
-When mounted inside containers, such as Rails 3.x, errors like "404 Not Found" or
+`Grape::Exceptions::InvalidVersionHeader`, which is raised when the version in the request header doesn't match the currently evaluated version for the endpoint, will _never_ be rescued from a `rescue_from` block (even a `rescue_from :all`) This is because Grape relies on Rack to catch that error and try the next versioned-route for cases where there exist identical Grape endpoints with different versions.
+
+### Rails 3.x
+
+When mounted inside containers, such as Rails 3.x, errors such as "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
@@ -1668,11 +1881,11 @@ For example, the following API will let you upload arbitrary files and return th
 
 ```ruby
 class Twitter::API < Grape::API
-  post "attachment" do
+  post 'attachment' do
     filename = params[:file][:filename]
     content_type MIME::Types.type_for(filename)[0].to_s
     env['api.format'] = :binary # there's no formatter for :binary, data will be returned "as is"
-    header "Content-Disposition", "attachment; filename*=UTF-8''#{URI.escape(filename)}"
+    header 'Content-Disposition', "attachment; filename*=UTF-8''#{URI.escape(filename)}"
     params[:file][:tempfile].read
   end
 end
@@ -1725,7 +1938,7 @@ If you do not want this behavior, set the default error formatter with `default_
 ```ruby
 class Twitter::API < Grape::API
   format :json
-  content_type :txt, "text/plain"
+  content_type :txt, 'text/plain'
   default_error_formatter :txt
 end
 ```
@@ -1734,8 +1947,8 @@ Custom formatters for existing and additional types can be defined with a proc.
 
 ```ruby
 class Twitter::API < Grape::API
-  content_type :xls, "application/vnd.ms-excel"
-  formatter :xls, lambda { |object, env| object.to_xls }
+  content_type :xls, 'application/vnd.ms-excel'
+  formatter :xls, ->(object, env) { object.to_xls }
 end
 ```
 
@@ -1749,7 +1962,7 @@ module XlsFormatter
 end
 
 class Twitter::API < Grape::API
-  content_type :xls, "application/vnd.ms-excel"
+  content_type :xls, 'application/vnd.ms-excel'
   formatter :xls, XlsFormatter
 end
 ```
@@ -1762,6 +1975,11 @@ Built-in formatters are the following.
 * `:serializable_hash`: use object's `serializable_hash` when available, otherwise fallback to `:json`
 * `:binary`: data will be returned "as is"
 
+Response statuses that indicate no content as defined by [Rack](https://github.com/rack)
+[here](https://github.com/rack/rack/blob/master/lib/rack/utils.rb#L567)
+will bypass serialization and the body entity - though there should be none -
+will not be modified.
+
 ### JSONP
 
 Grape supports JSONP via [Rack::JSONP](https://github.com/rack/rack-contrib), part of the
@@ -1807,7 +2025,7 @@ by setting the `Content-Type` header.
 ```ruby
 class API < Grape::API
   get '/home_timeline_js' do
-    content_type "application/javascript"
+    content_type 'application/javascript'
     "var statuses = ...;"
   end
 end
@@ -1835,11 +2053,11 @@ end
 ```
 
 ```ruby
-content_type :txt, "text/plain"
-content_type :custom, "text/custom"
+content_type :txt, 'text/plain'
+content_type :custom, 'text/custom'
 parser :custom, CustomParser
 
-put "value" do
+put 'value' do
   params[:value]
 end
 ```
@@ -1860,8 +2078,8 @@ hash may include `:with`, which defines the entity to expose.
 
 ### Grape Entities
 
-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)
+Add the [grape-entity](https://github.com/ruby-grape/grape-entity) gem to your Gemfile.
+Please refer to the [grape-entity documentation](https://github.com/ruby-grape/grape-entity/blob/master/README.md)
 for more details.
 
 The following example exposes statuses.
@@ -1871,9 +2089,9 @@ module API
   module Entities
     class Status < Grape::Entity
       expose :user_name
-      expose :text, documentation: { type: "string", desc: "Status update text." }
+      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 :user_type, :user_id, if: ->(status, options) { status.user.public? }
       expose :digest { |status, options| Digest::MD5.hexdigest(status.txt) }
       expose :replies, using: API::Status, as: :replies
     end
@@ -1981,12 +2199,12 @@ end
 
 ### Hypermedia and Roar
 
-You can use [Roar](https://github.com/apotonick/roar) to render HAL or Collection+JSON with the help of [grape-roar](https://github.com/dblock/grape-roar), which defines a custom JSON formatter and enables presenting entities with Grape's `present` keyword.
+You can use [Roar](https://github.com/apotonick/roar) to render HAL or Collection+JSON with the help of [grape-roar](https://github.com/ruby-grape/grape-roar), which defines a custom JSON formatter and enables presenting entities with Grape's `present` keyword.
 
 ### Rabl
 
 You can use [Rabl](https://github.com/nesquena/rabl) templates with the help of the
-[grape-rabl](https://github.com/LTe/grape-rabl) gem, which defines a custom Grape Rabl
+[grape-rabl](https://github.com/ruby-grape/grape-rabl) gem, which defines a custom Grape Rabl
 formatter.
 
 ### Active Model Serializers
@@ -2023,6 +2241,8 @@ end
 Use `body false` to return `204 No Content` without any data or content-type.
 
 You can also set the response to a file-like object with `file`.
+Note: Rack will read your entire Enumerable before returning a response. If
+you would like to stream the response, see `stream`.
 
 ```ruby
 class FileStreamer
@@ -2044,6 +2264,16 @@ class API < Grape::API
 end
 ```
 
+If you want a file-like object to be streamed using Rack::Chunked, use `stream`.
+
+```ruby
+class API < Grape::API
+  get '/' do
+    stream FileStreamer.new('file.bin')
+  end
+end
+```
+
 ## Authentication
 
 ### Basic and Digest Auth
@@ -2077,7 +2307,7 @@ For registering a Middleware you need the following options:
 * `label` - the name for your authenticator to use it later
 * `MiddlewareClass` - the MiddlewareClass to use for authentication
 * `option_lookup_proc` - A Proc with one Argument to lookup the options at
-runtime (return value is an `Array` as Paramter for the Middleware).
+runtime (return value is an `Array` as Parameter for the Middleware).
 
 Example:
 
@@ -2104,7 +2334,7 @@ Grape exposes arrays of API versions and compiled routes. Each route contains a
 ```ruby
 class TwitterAPI < Grape::API
   version 'v1'
-  desc "Includes custom settings."
+  desc 'Includes custom settings.'
   route_setting :custom, key: 'value'
   get do
 
@@ -2128,11 +2358,11 @@ It's possible to retrieve the information about the current route from within an
 
 ```ruby
 class MyAPI < Grape::API
-  desc "Returns a description of a parameter."
+  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
+  get 'params/:id' do
     route.route_params[params[:id]] # yields the parameter description
   end
 end
@@ -2173,7 +2403,7 @@ E.g. using `before`:
 
 ```ruby
 before do
-  header "X-Robots-Tag", "noindex"
+  header 'X-Robots-Tag', 'noindex'
 end
 ```
 
@@ -2298,12 +2528,12 @@ This will match all paths starting with '/statuses/'. There is one caveat though
 the `params[:status]` parameter only holds the first part of the request url.
 Luckily this can be circumvented by using the described above syntax for path
 specification and using the `PATH_INFO` Rack environment variable, using
-`env["PATH_INFO"]`. This will hold everything that comes after the '/statuses/'
+`env['PATH_INFO']`. This will hold everything that comes after the '/statuses/'
 part.
 
-# Using Custom Middleware
+## Using Custom Middleware
 
-## Rails Middleware
+### Rails Middleware
 
 Note that when you're using Grape mounted on Rails you don't have to use Rails middleware because it's already included into your middleware stack.
 You only have to implement the helpers to access the specific `env` variable.
@@ -2320,7 +2550,7 @@ class API < Grape::API
 
   helpers do
     def client_ip
-      env["action_dispatch.remote_ip"].to_s
+      env['action_dispatch.remote_ip'].to_s
     end
   end
 
@@ -2350,20 +2580,32 @@ describe Twitter::API do
     Twitter::API
   end
 
-  describe Twitter::API do
-    describe "GET /api/statuses/public_timeline" do
-      it "returns an empty array of statuses" do
-        get "/api/statuses/public_timeline"
-        expect(last_response.status).to eq(200)
-        expect(JSON.parse(last_response.body)).to eq []
-      end
+  context 'GET /api/statuses/public_timeline' do
+    it 'returns an empty array of statuses' do
+      get '/api/statuses/public_timeline'
+      expect(last_response.status).to eq(200)
+      expect(JSON.parse(last_response.body)).to eq []
     end
-    describe "GET /api/statuses/:id" do
-      it "returns a status by id" do
-        status = Status.create!
-        get "/api/statuses/#{status.id}"
-        expect(last_response.body).to eq status.to_json
-      end
+  end
+  context 'GET /api/statuses/:id' do
+    it 'returns a status by id' do
+      status = Status.create!
+      get "/api/statuses/#{status.id}"
+      expect(last_response.body).to eq status.to_json
+    end
+  end
+end
+```
+
+There's no standard way of sending arrays of objects via an HTTP GET, so POST JSON data and specify the correct content-type.
+
+```ruby
+describe Twitter::API do
+  context 'POST /api/statuses' do
+    it 'creates many statuses' do
+      statuses = [{ text: '...' }, { text: '...'}]
+      post '/api/statuses', statuses.to_json, 'CONTENT_TYPE' => 'application/json'
+      expect(last_response.body).to eq 201
     end
   end
 end
@@ -2381,8 +2623,8 @@ Airborne.configure do |config|
 end
 
 describe Twitter::API do
-  describe "GET /api/statuses/:id" do
-    it "returns a status by id" do
+  context 'GET /api/statuses/:id' do
+    it 'returns a status by id' do
       status = Status.create!
       get "/api/statuses/#{status.id}"
       expect_json(status.as_json)
@@ -2394,7 +2636,7 @@ end
 #### MiniTest
 
 ```ruby
-require "test_helper"
+require 'test_helper'
 
 class Twitter::APITest < MiniTest::Test
   include Rack::Test::Methods
@@ -2404,7 +2646,7 @@ class Twitter::APITest < MiniTest::Test
   end
 
   def test_get_api_statuses_public_timeline_returns_an_empty_array_of_statuses
-    get "/api/statuses/public_timeline"
+    get '/api/statuses/public_timeline'
     assert last_response.ok?
     assert_equal [], JSON.parse(last_response.body)
   end
@@ -2423,15 +2665,15 @@ end
 
 ```ruby
 describe Twitter::API do
-  describe "GET /api/statuses/public_timeline" do
-    it "returns an empty array of statuses" do
-      get "/api/statuses/public_timeline"
+  context 'GET /api/statuses/public_timeline' do
+    it 'returns an empty array of statuses' do
+      get '/api/statuses/public_timeline'
       expect(response.status).to eq(200)
       expect(JSON.parse(response.body)).to eq []
     end
   end
-  describe "GET /api/statuses/:id" do
-    it "returns a status by id" do
+  context 'GET /api/statuses/:id' do
+    it 'returns a status by id' do
       status = Status.create!
       get "/api/statuses/#{status.id}"
       expect(response.body).to eq status.to_json
@@ -2459,13 +2701,13 @@ class Twitter::APITest < ActiveSupport::TestCase
     Rails.application
   end
 
-  test "GET /api/statuses/public_timeline returns an empty array of statuses" do
-    get "/api/statuses/public_timeline"
+  test 'GET /api/statuses/public_timeline returns an empty array of statuses' do
+    get '/api/statuses/public_timeline'
     assert last_response.ok?
     assert_equal [], JSON.parse(last_response.body)
   end
 
-  test "GET /api/statuses/:id returns a status by id" do
+  test 'GET /api/statuses/:id returns a status by id' do
     status = Status.create!
     get "/api/statuses/#{status.id}"
     assert_equal status.to_json, last_response.body
@@ -2510,15 +2752,15 @@ Add API paths to `config/application.rb`.
 
 ```ruby
 # Auto-load API and its subdirectories
-config.paths.add File.join("app", "api"), glob: File.join("**", "*.rb")
-config.autoload_paths += Dir[Rails.root.join("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?
-  ActiveSupport::Dependencies.explicitly_unloadable_constants << "Twitter::API"
+  ActiveSupport::Dependencies.explicitly_unloadable_constants << 'Twitter::API'
 
   api_files = Dir[Rails.root.join('app', 'api', '**', '*.rb')]
   api_reloader = ActiveSupport::FileUpdateChecker.new(api_files) do
@@ -2534,9 +2776,39 @@ See [StackOverflow #3282655](http://stackoverflow.com/questions/3282655/ruby-on-
 
 ## Performance Monitoring
 
-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.
+### Active Support Instrumentation
+
+Grape has built-in support for [ActiveSupport::Notifications](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) which provides simple hook points to instrument key parts of your application.
+
+The following are currently supported:
+
+#### endpoint_run.grape
+
+The main execution of an endpoint, includes filters and rendering.
+
+* *endpoint* - The endpoint instance
+
+#### endpoint_render.grape
+
+The execution of the main content block of the endpoint.
+
+* *endpoint* - The endpoint instance
+
+#### endpoint_run_filters.grape
+
+* *endpoint* - The endpoint instance
+* *filters* - The filters being executed
+* *type* - The type of filters (before, before_validation, after_validation, after)
+
+See the [ActiveSupport::Notifications documentation](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) for information on how to subscribe to these events.
+
+### Monitoring Products
+
+Grape integrates with following third-party tools:
+
+* **New Relic** - [built-in support](https://docs.newrelic.com/docs/agents/ruby-agent/frameworks/grape-instrumentation) from v3.10.0 of the official [newrelic_rpm](https://github.com/newrelic/rpm) gem, also [newrelic-grape](https://github.com/xinminlabs/newrelic-grape) gem
+* **Librato Metrics** - [grape-librato](https://github.com/seanmoon/grape-librato) gem
+* **[Skylight](https://www.skylight.io/)** - [skylight](https://github.com/skylightio/skylight-ruby) gem, [documentation](https://docs.skylight.io/grape/)
 
 ## Contributing to Grape
 
@@ -2545,13 +2817,6 @@ features and discuss issues.
 
 See [CONTRIBUTING](CONTRIBUTING.md).
 
-## Hacking on Grape
-
-You can start hacking on Grape on
-[Nitrous.IO](https://www.nitrous.io/?utm_source=github.com&utm_campaign=grape&utm_medium=hackonnitrous) in a matter of seconds:
-
-[![Hack intridea/grape on Nitrous.IO](https://d3o0mnbgv6k92a.cloudfront.net/assets/hack-l-v1-3cc067e71372f6045e1949af9d96095b.png)](https://www.nitrous.io/hack_button?source=embed&runtime=rails&repo=intridea%2Fgrape&file_to_open=README.md)
-
 ## License
 
 MIT License. See LICENSE for details.