grape 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 065f62bd14d8e5f24acc6b085a2fd2f7b5cc835a
-  data.tar.gz: 1d95db90f66a6ddcae57416a557ac58977bae3b2
+  metadata.gz: 42e83be7840de205451cdb523c0a03f3a079300f
+  data.tar.gz: b16053b9a44c001cecae4f670de0073630b7b43e
 SHA512:
-  metadata.gz: 51324bbb02265b2ba09dae20e06039c1cdba09e4fd6f40979328be0bc32bd4fb03628ef90862c41016d14002b8b280906b945532d96b295ab8624dc567a57836
-  data.tar.gz: 93b0e47cbd02e8faad346d2e43b7f7d3bf56f05497331e87c6969dd17c65e8df651b69777e32f8aa9d68f6b17ae113e0094f6e04bf02fe25962959d71d7c7be5
+  metadata.gz: cd442f6727d63e80b631e36005c48ac93e639ad3bfd61f102cdcf2530dd67b528c9576e11bad705052108e7448181b74dd32fd4121100009e0bf42451eea6fa9
+  data.tar.gz: 8f79ccab0811111484bb920ae2b27edbe2c498db8e775fa063b4bf67655f5e6022e561fc22cfd6362e17e1ca27be2e857ef0ed51e8f34b00c4b4bed3e9e06847

data/.rubocop.yml

@@ -2,71 +2,6 @@ AllCops:
   Exclude:
     - vendor/**/*
     - bin/**/*
-
-LineLength:
-  Enabled: false
-
-MethodLength:
-  Enabled: false
-
-ClassLength:
-  Enabled: false
-
-Documentation:
-  # don't require classes to be documented
-  Enabled: false
-
-CollectionMethods:
-  # don't prefer map to collect, recuce to inject
-  Enabled: false
-
-Encoding:
-  # no need to always specify encoding
-  Enabled: false
-
-StringLiterals:
-  # use single or double-quoted strings, as you please
-  Enabled: false
-
-Void:
-  # == operator used in void context in specs
-  Enabled: false
-
-SignalException:
-  # prefer raise to fail
-  EnforcedStyle: only_raise
-
-RaiseArgs:
-  # don't care for what kind of raise
-  Enabled: false
-
-PerlBackrefs:
-  # TODO: regular expression matching with $1, $2, etc.
-  Enabled: false
-
-BlockNesting:
-  # TODO: fix too much nesting
-  Max: 4
-
-Lambda:
-  # TODO: replace all lambda with -> or Proc
-  Enabled: false
-
-Blocks:
-  # allow multi-line blocks like expect { }
-  Enabled: false
-
-WordArray:
-  # %w vs. [ '', ... ]
-  Enabled: false
-
-CyclomaticComplexity:
-  Enabled: false
-
-DoubleNegation:
-  Enabled: false
-
-PredicateName:
-  Enabled: false
+    - gemfiles/**/*
 
 inherit_from: .rubocop_todo.yml

data/.rubocop_todo.yml

@@ -1,64 +1,125 @@
 # This configuration was generated by `rubocop --auto-gen-config`
-# on 2014-08-12 13:16:39 +0200 using RuboCop version 0.24.1.
+# on 2014-12-16 11:52:50 -0500 using RuboCop version 0.28.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 28
+# Offense count: 29
 # Cop supports --auto-correct.
 Lint/UnusedBlockArgument:
   Enabled: false
 
-# Offense count: 30
+# Offense count: 26
 # Cop supports --auto-correct.
 Lint/UnusedMethodArgument:
   Enabled: false
 
-# Offense count: 5
+# Offense count: 35
+Metrics/AbcSize:
+  Max: 50
+
+# Offense count: 1
+Metrics/BlockNesting:
+  Max: 4
+
+# Offense count: 4
+# Configuration parameters: CountComments.
+Metrics/ClassLength:
+  Max: 243
+
+# Offense count: 15
+Metrics/CyclomaticComplexity:
+  Max: 19
+
+# Offense count: 545
+# Configuration parameters: AllowURI, URISchemes.
+Metrics/LineLength:
+  Max: 198
+
+# Offense count: 42
+# Configuration parameters: CountComments.
+Metrics/MethodLength:
+  Max: 35
+
+# Offense count: 13
+Metrics/PerceivedComplexity:
+  Max: 21
+
+# Offense count: 26
+# Cop supports --auto-correct.
+Style/Blocks:
+  Enabled: false
+
+# Offense count: 6
 # Cop supports --auto-correct.
 # Configuration parameters: EnforcedStyle, SupportedStyles.
 Style/ClassCheck:
   Enabled: false
 
-# Offense count: 6
+# Offense count: 157
+Style/Documentation:
+  Enabled: false
+
+# Offense count: 7
+Style/DoubleNegation:
+  Enabled: false
+
+# Offense count: 5
 Style/EachWithObject:
   Enabled: false
 
-# Offense count: 11
+# Offense count: 1
+Style/EmptyElse:
+  Enabled: false
+
+# Offense count: 14
 # Configuration parameters: MinBodyLength.
 Style/GuardClause:
   Enabled: false
 
-# Offense count: 1
+# Offense count: 3
 # Cop supports --auto-correct.
 # Configuration parameters: EnforcedStyle, SupportedStyles.
 Style/HashSyntax:
   Enabled: false
 
-# Offense count: 14
+# Offense count: 15
 # Cop supports --auto-correct.
 Style/IndentArray:
   Enabled: false
 
-# Offense count: 2
-# Cop supports --auto-correct.
-# Configuration parameters: EnforcedStyle, SupportedStyles.
-Style/IndentHash:
-  Enabled: true
+# Offense count: 18
+Style/Lambda:
+  Enabled: false
 
-# Offense count: 3
-# Configuration parameters: EnforcedStyle, SupportedStyles.
+# Offense count: 1
+# Configuration parameters: EnforcedStyle, MinBodyLength, SupportedStyles.
 Style/Next:
   Enabled: false
 
-# Offense count: 2
+# Offense count: 3
 # Cop supports --auto-correct.
 # Configuration parameters: PreferredDelimiters.
 Style/PercentLiteralDelimiters:
   Enabled: false
 
-# Offense count: 1
+# Offense count: 3
+# Configuration parameters: NamePrefix, NamePrefixBlacklist.
+Style/PredicateName:
+  Enabled: false
+
+# Offense count: 9
+# Configuration parameters: EnforcedStyle, SupportedStyles.
+Style/RaiseArgs:
+  Enabled: false
+
+# Offense count: 4
+# Configuration parameters: MaxSlashes.
+Style/RegexpLiteral:
+  Enabled: false
+
+# Offense count: 4
 # Cop supports --auto-correct.
 # Configuration parameters: EnforcedStyle, SupportedStyles.
 Style/SpaceBeforeBlockBraces:

data/.travis.yml

@@ -1,10 +1,9 @@
 language: ruby
 
-cache: bundler
+sudo: false
 
 rvm:
-  - 2.1.2
-  - 2.1.0
+  - 2.1
   - 2.0.0
   - 1.9.3
   - rbx-2.2.10
@@ -16,3 +15,8 @@ matrix:
   allow_failures:
     - rvm: ruby-head
     - rvm: jruby-head
+
+gemfile:
+  - Gemfile
+  - gemfiles/rails_3.gemfile
+  - gemfiles/rails_4.gemfile

data/Appraisals

@@ -0,0 +1,7 @@
+appraise "rails-3" do
+  gem "rails", "3.2.19"
+end
+
+appraise "rails-4" do
+  gem "rails", "4.1.6"
+end

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+0.10.0 (12/19/2014)
+===================
+
+* [#803](https://github.com/intridea/grape/pull/803), [#820](https://github.com/intridea/grape/pull/820): Added `all_or_none_of` parameter validator - [@loveltyoic](https://github.com/loveltyoic), [@natecj](https://github.com/natecj).
+* [#774](https://github.com/intridea/grape/pull/774): Extended `mutually_exclusive`, `exactly_one_of`, `at_least_one_of` to work inside any kind of group: `requires` or `optional`, `Hash` or `Array` - [@ShPakvel](https://github.com/ShPakvel).
+* [#743](https://github.com/intridea/grape/pull/743): Added `allow_blank` parameter validator to validate non-empty strings - [@elado](https://github.com/elado).
+* [#745](https://github.com/intridea/grape/pull/745): Removed `atom+xml`, `rss+xml`, and `jsonapi` content-types - [@akabraham](https://github.com/akabraham).
+* [#745](https://github.com/intridea/grape/pull/745): Added `:binary, application/octet-stream` content-type - [@akabraham](https://github.com/akabraham).
+* [#757](https://github.com/intridea/grape/pull/757): Changed `desc` can now be used with a block syntax - [@dspaeth-faber](https://github.com/dspaeth-faber).
+* [#779](https://github.com/intridea/grape/pull/779): Fixed using `values` with a `default` proc - [@ShPakvel](https://github.com/ShPakvel).
+* [#799](https://github.com/intridea/grape/pull/799): Fixed custom validators with required `Hash`, `Array` types - [@bwalex](https://github.com/bwalex).
+* [#784](https://github.com/intridea/grape/pull/784): Fixed `present` to not overwrite the previously added contents of the response body whebn called more than once - [@mfunaro](https://github.com/mfunaro).
+* [#809](https://github.com/intridea/grape/pull/809): Removed automatic `(.:format)` suffix on paths if you're using only one format (e.g., with `format :json`, `/path` will respond with JSON but `/path.xml` will be a 404) - [@ajvondrak](https://github.com/ajvondrak).
+* [#816](https://github.com/intridea/grape/pull/816): Added ability to filter out missing params if params is a nested hash with `declared(params, include_missing: false)` - [@georgimitev](https://github.com/georgimitev).
+* [#819](https://github.com/intridea/grape/pull/819): Allowed both `desc` and `description` in the params DSL - [@mzikherman](https://github.com/mzikherman).
+* [#821](https://github.com/intridea/grape/pull/821): Fixed passing string value when hash is expected in params - [@rebelact](https://github.com/rebelact).
+* [#824](https://github.com/intridea/grape/pull/824): Validate array params against list of acceptable values - [@dnd](https://github.com/dnd).
+* [#813](https://github.com/intridea/grape/pull/813): Routing methods dsl refactored to get rid of explicit `paths` parameter - [@AlexYankee](https://github.com/AlexYankee).
+* [#826](https://github.com/intridea/grape/pull/826): Find `coerce_type` for `Array` when not specified - [@manovotn](https://github.com/manovotn).
+* [#645](https://github.com/intridea/grape/issues/645): Invoking `body false` will return `204 No Content` - [@dblock](https://github.com/dblock).
+* [#801](https://github.com/intridea/grape/issues/801): Only evaluate permitted parameter `values` and `default` lazily on each request when declared as a proc - [@dblock](https://github.com/dblock).
+* [#679](https://github.com/intridea/grape/issues/679): Fixed `OPTIONS` method returning 404 when combined with `prefix`- [@dblock](https://github.com/dblock).
+* [#679](https://github.com/intridea/grape/issues/679): Fixed unsupported methods returning 404 instead of 405 when combined with `prefix`- [@dblock](https://github.com/dblock).
+
 0.9.0 (8/27/2014)
 =================
 

data/CONTRIBUTING.md

@@ -32,6 +32,13 @@ bundle install
 bundle exec rake
 ```
 
+Run tests against all supported versions of Rails.
+
+```
+appraisal install
+appraisal rake spec
+```
+
 #### Write Tests
 
 Try to write a test that reproduces the problem you're trying to fix or describes a feature that you want to build. Add to [spec/grape](spec/grape).

data/Gemfile

@@ -3,14 +3,8 @@ source 'http://rubygems.org'
 gemspec
 
 group :development, :test do
-  gem 'rubocop', '~> 0.24.1'
+  gem 'rubocop', '~> 0.28.0'
   gem 'guard'
   gem 'guard-rspec'
   gem 'guard-rubocop'
 end
-
-platforms :rbx do
-  gem 'rubysl'
-  gem 'rubinius-developer_tools'
-  gem 'racc'
-end

data/Guardfile

@@ -1,7 +1,7 @@
 guard :rspec, all_on_start: true, cmd: 'bundle exec rspec' do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
-  watch('spec/spec_helper.rb')  { "spec" }
+  watch('spec/spec_helper.rb')  { 'spec' }
 end
 
 guard :rubocop do

data/README.md

@@ -11,6 +11,7 @@
 - [Basic Usage](#basic-usage)
 - [Mounting](#mounting)
   - [Rack](#rack)
+  - [ActiveRecord without Rails](#activerecord-without-rails)
   - [Alongside Sinatra (or other frameworks)](#alongside-sinatra-or-other-frameworks)
   - [Rails](#rails)
   - [Modules](#modules)
@@ -21,7 +22,10 @@
   - [Param](#param)
 - [Describing Methods](#describing-methods)
 - [Parameters](#parameters)
+  - [Declared](#declared)
+  - [Include Missing](#include-missing)
 - [Parameter Validation and Coercion](#parameter-validation-and-coercion)
+  - [Built-in Validators](#built-in-validators)
   - [Namespace Validation and Coercion](#namespace-validation-and-coercion)
   - [Custom Validators](#custom-validators)
   - [Validation Errors](#validation-errors)
@@ -50,17 +54,22 @@
   - [Hypermedia](#hypermedia)
   - [Rabl](#rabl)
   - [Active Model Serializers](#active-model-serializers)
+- [Sending Raw or No Data](#sending-raw-or-no-data)
 - [Authentication](#authentication)
 - [Describing and Inspecting an API](#describing-and-inspecting-an-api)
 - [Current Route and Endpoint](#current-route-and-endpoint)
 - [Before and After](#before-and-after)
 - [Anchoring](#anchoring)
+- [Using Custom Middleware](#using-custom-middleware)
+  - [Rails Middleware](#rails-middleware)
+    - [Remote IP](#remote-ip)
 - [Writing Tests](#writing-tests)
   - [Writing Tests with Rack](#writing-tests-with-rack)
   - [Writing Tests with Rails](#writing-tests-with-rails)
   - [Stubbing Helpers](#stubbing-helpers)
 - [Reloading API Changes in Development](#reloading-api-changes-in-development)
-  - [Rails 3.x](#rails-3x)
+  - [Reloading in Rack Applications](#reloading-in-rack-applications)
+  - [Reloading in Rails Applications](#reloading-in-rails-applications)
 - [Performance Monitoring](#performance-monitoring)
 - [Contributing to Grape](#contributing-to-grape)
 - [Hacking on Grape](#hacking-on-grape)
@@ -77,7 +86,8 @@ content negotiation, versioning and much more.
 
 ## Stable Release
 
-You're reading the documentation for Grape [0.9.0](https://github.com/intridea/grape/blob/v0.9.0/README.md).
+You're reading the documentation for the stable release of Grape, 0.10.0.
+Please read [UPGRADING](UPGRADING.md) when upgrading from a previous version.
 
 ## Project Resources
 
@@ -107,6 +117,7 @@ module Twitter
   class API < Grape::API
     version 'v1', using: :header, vendor: 'twitter'
     format :json
+    prefix :api
 
     helpers do
       def current_user
@@ -191,15 +202,29 @@ run Twitter::API
 
 And would respond to the following routes:
 
-    GET /statuses/public_timeline(.json)
-    GET /statuses/home_timeline(.json)
-    GET /statuses/:id(.json)
-    POST /statuses(.json)
-    PUT /statuses/:id(.json)
-    DELETE /statuses/:id(.json)
+    GET /api/statuses/public_timeline
+    GET /api/statuses/home_timeline
+    GET /api/statuses/:id
+    POST /api/statuses
+    PUT /api/statuses/:id
+    DELETE /api/statuses/:id
 
 Grape will also automatically respond to HEAD and OPTIONS for all GET, and just OPTIONS for all other routes.
 
+### ActiveRecord without Rails
+
+If you want to use ActiveRecord within Grape, you will need to make sure that ActiveRecord's connection pool
+is handled correctly.
+
+The easiest way to achieve that is by using ActiveRecord's `ConnectionManagement` middleware in your
+`config.ru` before mounting Grape, e.g.:
+
+```ruby
+use ActiveRecord::ConnectionAdapters::ConnectionManagement
+
+run Twitter::API
+```
+
 ### Alongside Sinatra (or other frameworks)
 
 If you wish to mount Grape alongside another Rack framework such as Sinatra, you can do so easily using
@@ -244,6 +269,13 @@ Modify `config/routes`:
 mount Twitter::API => '/'
 ```
 
+Additionally, if the version of your Rails is 4.0+ and the application uses the default model layer of ActiveRecord, you will want to use the `hashie_rails` [gem](http://rubygems.org/gems/hashie_rails). This gem disables the security feature of `strong_params` at the model layer, allowing you the use of Grape's own params validation instead.
+
+```ruby
+# Gemfile
+gem "hashie_rails"
+```
+
 See below for additional code that enables reloading of API changes in development.
 
 ### Modules
@@ -355,12 +387,34 @@ version 'v1', using: :param, parameter: "v"
 You can add a description to API methods and namespaces.
 
 ```ruby
-desc "Returns your public timeline."
+desc "Returns your public timeline." do
+  detail 'more details'
+  params  API::Entities::Status.documentation
+  success API::Entities::Entity
+  failure [[401, 'Unauthorized', "Entities::Error"]]
+  named 'My named route'
+  headers [XAuthToken: {
+             description: 'Valdates your identity',
+             required: true
+           },
+           XOptionalHeader: {
+             description: 'Not really needed',
+            required: false
+           }
+          ]
+end
 get :public_timeline do
   Status.limit(20)
 end
 ```
 
+* `detail`: A more enhanced description
+* `params`: Define parameters directly from an `Entity`
+* `success`: (former entity) The `Entity` to be used to present by default this route
+* `failure`: (former http_codes) A definition of the used failure HTTP Codes and Entities
+* `named`: A helper to give a route a name and find it with this name in the documentation Hash
+* `headers`: A definition of the used Headers
+
 ## Parameters
 
 Request parameters are available through the `params` hash object. This includes `GET`, `POST`
@@ -413,6 +467,176 @@ In the case of conflict between either of:
 
 route string parameters will have precedence.
 
+#### 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:
+
+````ruby
+format :json
+
+post 'users/signup' do
+  { "declared_params" => declared(params) }
+end
+````
+
+If we do not specify any params, declared will return an empty hash.
+
+**Request**
+
+````bash
+curl -X POST -H "Content-Type: application/json" localhost:9292/users/signup -d '{"user": {"first_name":"first name", "last_name": "last name"}}'
+````
+
+**Response**
+
+````json
+{
+  "declared_params": {}
+}
+
+````
+
+Once we add parameters requirements, grape will start returning only the declared params.
+
+````ruby
+format :json
+
+params do
+  requires :user, type: Hash do
+    requires :first_name, type: String
+    requires :last_name, type: String
+  end
+end
+
+post 'users/signup' do
+  { "declared_params" => declared(params) }
+end
+````
+
+**Request**
+
+````bash
+curl -X POST -H "Content-Type: application/json" localhost:9292/users/signup -d '{"user": {"first_name":"first name", "last_name": "last name", "random": "never shown"}}'
+````
+
+**Response**
+
+````json
+{
+  "declared_params": {
+    "user": {
+      "first_name": "first name",
+      "last_name": "last name"
+    }
+  }
+}
+````
+
+#### 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:
+
+````ruby
+format :json
+
+params do
+  requires :first_name, type: String
+  optional :last_name, type: String
+end
+
+post 'users/signup' do
+  { "declared_params" => declared(params, include_missing: false) }
+end
+````
+
+**Request**
+
+````bash
+curl -X POST -H "Content-Type: application/json" localhost:9292/users/signup -d '{"user": {"first_name":"first name", "random": "never shown"}}'
+````
+
+**Response with include_missing:false**
+
+````json
+{
+  "declared_params": {
+    "user": {
+      "first_name": "first name"
+    }
+  }
+}
+````
+
+**Response with include_missing:true**
+
+````json
+{
+  "declared_params": {
+    "first_name": "first name",
+    "last_name": null
+  }
+}
+````
+
+It also works on nested hashes:
+
+````ruby
+format :json
+
+params do
+  requires :user, :type => Hash do
+    requires :first_name, type: String
+    optional :last_name, type: String
+    requires :address, :type => Hash do
+      requires :city, type: String
+      optional :region, type: String
+    end
+  end
+end
+
+post 'users/signup' do
+  { "declared_params" => declared(params, include_missing: false) }
+end
+````
+
+**Request**
+
+````bash
+curl -X POST -H "Content-Type: application/json" localhost:9292/users/signup -d '{"user": {"first_name":"first name", "random": "never shown", "address": { "city": "SF"}}}'
+````
+
+**Response with include_missing:false**
+
+````json
+{
+  "declared_params": {
+    "user": {
+      "first_name": "first name",
+      "address": {
+        "city": "SF"
+      }
+    }
+  }
+}
+````
+
+**Response with include_missing:true**
+
+````json
+{
+  "declared_params": {
+    "user": {
+      "first_name": "first name",
+      "last_name": null,
+      "address": {
+        "city": "Zurich",
+        "region": null
+      }
+    }
+  }
+}
+````
+
 ## Parameter Validation and Coercion
 
 You can define validations and coercion options for your parameters using a `params` block.
@@ -447,27 +671,25 @@ params do
 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.
+Note that default values will be passed through to any validation options specified.
+The following example will always fail if `:color` is not explicitly provided.
 
 ```ruby
 params do
-  requires :status, type: Symbol, values: [:not_started, :processing, :done]
+  optional :color, type: String, default: 'blue', values: ['red', 'green']
 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.
+The correct implementation is to ensure the default value passes all validations.
 
 ```ruby
 params do
-  requires :hashtag, type: String, values: -> { Hashtag.all.map(&:tag) }
+  optional :color, type: String, default: 'blue', values: ['blue', 'red', 'green']
 end
 ```
 
+#### 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]`,
 and `params[:audio][:format]` is required only if `params[:audio]` is present.
@@ -489,6 +711,66 @@ params do
 end
 ```
 
+### Built-in Validators
+
+#### `allow_blank`
+
+Parameters can be defined as `allow_blank`, ensuring that they contain a value. By default, `requires`
+only validates that a parameter was sent in the request, regardless its value. With `allow_blank`,
+empty values or whitespace only values are invalid.
+
+`allow_blank` can be combined with both `requires` and `optional`. If the parameter is required, it has to contain
+a value. If it's optional, it's possible to not send it in the request, but if it's being sent, it has to have
+some value, and not an empty string/only whitespaces.
+
+
+```ruby
+params do
+  requires :username, allow_blank: false
+  optional :first_name, allow_blank: false
+end
+```
+
+#### `values`
+
+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
+lazily with each request use a lambda, like `:random_number` above.
+
+```ruby
+params do
+  requires :status, type: Symbol, values: [:not_started, :processing, :done]
+  optional :numbers, type: Array[Integer], default: 1, values: [1, 2, 3, 5, 8]
+end
+```
+
+The `:values` option can also be supplied with a `Proc`, evaluated lazily with each request.
+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
+  requires :hashtag, type: String, values: -> { Hashtag.all.map(&:tag) }
+end
+```
+
+#### `regexp`
+
+Parameters can be restricted to match a specific regular expression with the `:regexp` option. If the value
+is nil or does not match the regular expression an error will be returned. Note that this is true for both `requires`
+and `optional` parameters.
+
+```ruby
+params do
+  requires :email, regexp: /.+@.+/
+end
+```
+
+
+#### `mutually_exclusive`
+
 Parameters can be defined as `mutually_exclusive`, ensuring that they aren't present at the same time in a request.
 
 ```ruby
@@ -514,6 +796,8 @@ end
 
 **Warning**: Never define mutually exclusive sets with any required params. Two mutually exclusive required params will mean params are never valid, thus making the endpoint useless. One required param mutually exclusive with an optional param will mean the latter is never valid.
 
+#### `exactly_one_of`
+
 Parameters can be defined as 'exactly_one_of', ensuring that exactly one parameter gets selected.
 
 ```ruby
@@ -524,6 +808,8 @@ params do
 end
 ```
 
+#### `at_least_one_of`
+
 Parameters can be defined as 'at_least_one_of', ensuring that at least one parameter gets selected.
 
 ```ruby
@@ -531,7 +817,51 @@ params do
   optional :beer
   optional :wine
   optional :juice
-  at_least_one :beer, :wine, :juice
+  at_least_one_of :beer, :wine, :juice
+end
+```
+
+#### `all_or_none_of`
+
+Parameters can be defined as 'all_or_none_of', ensuring that all or none of parameters gets selected.
+
+```ruby
+params do
+  optional :beer
+  optional :wine
+  optional :juice
+  all_or_none_of :beer, :wine, :juice
+end
+```
+
+#### Nested `mutually_exclusive`, `exactly_one_of`, `at_least_one_of`, `all_or_none_of`
+
+All of these methods can be used at any nested level.
+
+```ruby
+params do
+  requires :food do
+    optional :meat
+    optional :fish
+    optional :rice
+    at_least_one_of :meat, :fish, :rice
+  end
+  group :drink do
+    optional :beer
+    optional :wine
+    optional :juice
+    exactly_one_of :beer, :wine, :juice
+  end
+  optional :dessert do
+    optional :cake
+    optional :icecream
+    mutually_exclusive :cake, :icecream
+  end
+  optional :recipe do
+    optional :oil
+    optional :meat
+    all_or_none_of :oil, :meat
+  end
 end
 ```
 
@@ -579,10 +909,10 @@ end
 ### Custom Validators
 
 ```ruby
-class AlphaNumeric < Grape::Validations::Validator
+class AlphaNumeric < Grape::Validations::Base
   def validate_param!(attr_name, params)
     unless params[attr_name] =~ /^[[:alnum:]]+$/
-      raise Grape::Exceptions::Validation, param: @scope.full_name(attr_name), message: "must consist of alpha-numeric characters"
+      raise Grape::Exceptions::Validation, params: [@scope.full_name(attr_name)], message: "must consist of alpha-numeric characters"
     end
   end
 end
@@ -597,10 +927,10 @@ end
 You can also create custom classes that take parameters.
 
 ```ruby
-class Length < Grape::Validations::SingleOptionValidator
+class Length < Grape::Validations::Base
   def validate_param!(attr_name, params)
     unless params[attr_name].length <= @option
-      raise Grape::Exceptions::Validation, param: @scope.full_name(attr_name), message: "must be at the most #{@option} characters long"
+      raise Grape::Exceptions::Validation, params: [@scope.full_name(attr_name)], message: "must be at the most #{@option} characters long"
     end
   end
 end
@@ -956,14 +1286,18 @@ end
 The following example specifies the entity to use in the `http_codes` definition.
 
 ```
-desc 'My Route', http_codes: [[408, 'Unauthorized', API::Error]]
+desc 'My Route' do
+ failure [[408, 'Unauthorized', API::Error]]
+end
 error!({ message: 'Unauthorized' }, 408)
 ```
 
 The following example specifies the presented entity explicitly in the error message.
 
 ```ruby
-desc 'My Route', http_codes: [[408, 'Unauthorized']]
+desc 'My Route' do
+ failure [[408, 'Unauthorized']]
+end
 error!({ message: 'Unauthorized', with: API::Error }, 408)
 ```
 
@@ -1176,16 +1510,115 @@ end
 
 ## API Formats
 
-By default, Grape supports _XML_, _JSON_, and _TXT_ content-types. The default format is `:txt`.
+Your API can declare which content-types to support by using `content_type`. If you do not specify any, Grape will support
+_XML_, _JSON_, _BINARY_, and _TXT_ content-types. The default format is `:txt`; you can change this with `default_format`.
+Essentially, the two APIs below are equivalent.
+
+```ruby
+class Twitter::API < Grape::API
+  # no content_type declarations, so Grape uses the defaults
+end
+
+class Twitter::API < Grape::API
+  # the following declarations are equivalent to the defaults
+
+  content_type :xml, 'application/xml'
+  content_type :json, 'application/json'
+  content_type :binary, 'application/octet-stream'
+  content_type :txt, 'text/plain'
+
+  default_format :txt
+end
+```
+
+If you declare any `content_type` whatsoever, the Grape defaults will be overridden. For example, the following API will only
+support the `:xml` and `:rss` content-types, but not `:txt`, `:json`, or `:binary`. Importantly, this means the `:txt`
+default format is not supported! So, make sure to set a new `default_format`.
+
+```ruby
+class Twitter::API < Grape::API
+  content_type :xml, 'application/xml'
+  content_type :rss, 'application/xml+rss'
+
+  default_format :xml
+end
+```
+
+Serialization takes place automatically. For example, you do not have to call `to_json` in each JSON API endpoint
+implementation. The response format (and thus the automatic serialization) is determined in the following order:
+* Use the file extension, if specified. If the file is .json, choose the JSON format.
+* 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`.
+
+For example, consider the following API.
+
+```ruby
+class MultipleFormatAPI < Grape::API
+  content_type :xml, 'application/xml'
+  content_type :json, 'application/json'
+
+  default_format :json
+
+  get :hello do
+    { hello: 'world' }
+  end
+end
+```
+
+* `GET /hello` (with an `Accept: */*` header) does not have an extension or a `format` parameter, so it will respond with
+  JSON (the default format).
+* `GET /hello.xml` has a recognized extension, so it will respond with XML.
+* `GET /hello?format=xml` has a recognized `format` parameter, so it will respond with XML.
+* `GET /hello.xml?format=json` has a recognized extension (which takes precedence over the `format` parameter), so it will
+  respond with XML.
+* `GET /hello.xls` (with an `Accept: */*` header) has an extension, but that extension is not recognized, so it will respond
+  with JSON (the default format).
+* `GET /hello.xls` with an `Accept: application/xml` header has an unrecognized extension, but the `Accept` header
+  corresponds to a recognized format, so it will respond with XML.
+* `GET /hello.xls` with an `Accept: text/plain` header has an unrecognized extension *and* an unrecognized `Accept` header,
+  so it will respond with JSON (the default format).
+
+You can override this process explicitly by specifying `env['api.format']` in the API itself.
+For example, the following API will let you upload arbitrary files and return their contents as an attachment with the correct MIME type.
+
+```ruby
+class Twitter::API < Grape::API
+  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)}"
+    params[:file][:tempfile].read
+  end
+end
+```
+
+You can have your API only respond to a single format with `format`. If you use this, the API will **not** respond to file
+extensions. For example, consider the following API.
+
+```ruby
+class SingleFormatAPI < Grape::API
+  format :json
 
-Serialization takes place automatically. For example, you do not have to call `to_json` in each JSON API implementation.
+  get :hello do
+    { hello: 'world' }
+  end
+end
+```
 
-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.
+* `GET /hello` will respond with JSON.
+* `GET /hello.xml`, `GET /hello.json`, `GET /hello.foobar`, or *any* other extension will respond with an HTTP 404 error code.
+* `GET /hello?format=xml` will respond with an HTTP 406 error code, because the XML format specified by the request parameter
+  is not supported.
+* `GET /hello` with an `Accept: application/xml` header will still respond with JSON, since it could not negotiate a
+  recognized content-type from the headers and JSON is the effective default.
 
-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
-will fail with an HTTP 406 error code.
+The formats apply to parsing, too. 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 will fail with an HTTP 406 error code.
 
 ```ruby
 class Twitter::API < Grape::API
@@ -1238,45 +1671,13 @@ class Twitter::API < Grape::API
 end
 ```
 
-Built-in formats are the following.
+Built-in formatters are the following.
 
-* `:json` and `:jsonapi`: use object's `to_json` when available, otherwise call `MultiJson.dump`
+* `:json`: 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`
-
-Use `default_format` to set the fallback format when the format could not be determined from the `Accept` header.
-See below for the order for choosing the API format.
-
-```ruby
-class Twitter::API < Grape::API
-  default_format :json
-end
-```
-
-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 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`.
-
-You can override this process explicitly by specifying `env['api.format']` in the API itself.
-For example, the following API will let you upload arbitrary files and return their contents as an attachment with the correct MIME type.
-
-```ruby
-class Twitter::API < Grape::API
-  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)}"
-    params[:file][:tempfile].read
-  end
-end
-```
+* `:binary`: data will be returned "as is"
 
 ### JSONP
 
@@ -1398,9 +1799,9 @@ module API
   class Statuses < Grape::API
     version 'v1'
 
-    desc 'Statuses index', {
+    desc 'Statuses index' do
       params: API::Entities::Status.documentation
-    }
+    end
     get '/statuses' do
       statuses = Status.all
       type = current_user.admin? ? :full : :default
@@ -1486,6 +1887,32 @@ You can use [Active Model Serializers](https://github.com/rails-api/active_model
 [grape-active_model_serializers](https://github.com/jrhe/grape-active_model_serializers) gem, which defines a custom Grape AMS
 formatter.
 
+## Sending Raw or No Data
+
+In general, use the binary format to send raw data.
+
+```ruby
+class API < Grape::API
+  get '/file' do
+    content_type 'application/octet-stream'
+    File.binread 'file.bin'
+  end
+end
+```
+
+You can also set the response body explicitly with `body`.
+
+```ruby
+class API < Grape::API
+  get '/' do
+    content_type 'text/plain'
+    body 'Hello World'
+    # return value ignored
+  end
+end
+```
+
+Use `body false` to return `204 No Content` without any data or content-type.
 
 ## Authentication
 
@@ -1515,7 +1942,7 @@ Grape can use custom Middleware for authentication. How to implement these
 Middleware have a look at `Rack::Auth::Basic` or similar implementations.
 
 
-For registering a Middlewar you need the following options:
+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
@@ -1529,7 +1956,7 @@ Example:
 Grape::Middleware::Auth::Strategies.add(:my_auth, AuthMiddleware, ->(options) { [options[:realm]] } )
 
 
-auth :my_auth ,{ real: 'Test Api'} do |credentials|
+auth :my_auth, { realm: 'Test Api'} do |credentials|
   # lookup the user's password here
   { 'user1' => 'password1' }[username]
 end
@@ -1540,26 +1967,34 @@ Use [warden-oauth2](https://github.com/opperator/warden-oauth2) or [rack-oauth2]
 
 ## Describing and Inspecting an API
 
-Grape routes can be reflected at runtime. This can notably be useful for generating
-documentation.
+Grape routes can be reflected at runtime. This can notably be useful for generating documentation.
+
+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`. You can add custom route settings to the route metadata with `route_setting`.
+
+```ruby
+class TwitterAPI < Grape::API
+  version 'v1'
+  desc "Includes custom settings."
+  route_setting :custom, key: 'value'
+  get do
 
-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
-accessible via dynamically-generated `route_[name]` functions.
+  end
+end
+```
+
+Examine the routes at runtime.
 
 ```ruby
 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 # etc.
+TwitterAPI::routes[0].route_version # => 'v1'
+TwitterAPI::routes[0].route_description # => 'Includes custom settings.'
+TwitterAPI::routes[0].route_settings[:custom] # => { key: 'value' }
 ```
 
 ## Current Route and Endpoint
 
-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
@@ -1703,6 +2138,35 @@ specification and using the `PATH_INFO` Rack environment variable, using
 `env["PATH_INFO"]`. This will hold everything that comes after the '/statuses/'
 part.
 
+# Using Custom 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.
+
+### Remote IP
+
+By default you can access remote IP with `request.ip`. This is the remote IP address implemented by Rack. Sometimes it is desirable to get the remote IP [Rails-style](http://stackoverflow.com/questions/10997005/whats-the-difference-between-request-remote-ip-and-request-ip-in-rails) with `ActionDispatch::RemoteIp`.
+
+Add `gem 'actionpack'` to your Gemfile and `require 'action_dispatch/middleware/remote_ip.rb'`. Use the middleware in your API and expose a `client_ip` helper. See [this documentation](http://api.rubyonrails.org/classes/ActionDispatch/RemoteIp.html) for additional options.
+
+```ruby
+class API < Grape::API
+  use ActionDispatch::RemoteIp
+
+  helpers do
+    def client_ip
+      env["action_dispatch.remote_ip"].to_s
+    end
+  end
+
+  get :remopte_ip do
+    { ip: client_ip }
+  end
+end
+```
+
 ## Writing Tests
 
 You can test a Grape API with RSpec by making HTTP requests and examining the response.
@@ -1722,17 +2186,17 @@ describe Twitter::API do
   end
 
   describe Twitter::API do
-    describe "GET /api/v1/statuses" do
+    describe "GET /api/statuses/public_timeline" do
       it "returns an empty array of statuses" do
-        get "/api/v1/statuses"
+        get "/api/statuses/public_timeline"
         expect(last_response.status).to eq(200)
         expect(JSON.parse(last_response.body)).to eq []
       end
     end
-    describe "GET /api/v1/statuses/:id" do
+    describe "GET /api/statuses/:id" do
       it "returns a status by id" do
         status = Status.create!
-        get "/api/v1/statuses/#{status.id}"
+        get "/api/statuses/#{status.id}"
         expect(last_response.body).to eq status.to_json
       end
     end
@@ -1744,17 +2208,17 @@ end
 
 ```ruby
 describe Twitter::API do
-  describe "GET /api/v1/statuses" do
+  describe "GET /api/statuses/public_timeline" do
     it "returns an empty array of statuses" do
-      get "/api/v1/statuses"
+      get "/api/statuses/public_timeline"
       expect(response.status).to eq(200)
       expect(JSON.parse(response.body)).to eq []
     end
   end
-  describe "GET /api/v1/statuses/:id" do
+  describe "GET /api/statuses/:id" do
     it "returns a status by id" do
       status = Status.create!
-      get "/api/v1/statuses/#{status.id}"
+      get "/api/statuses/#{status.id}"
       expect(response.body).to eq status.to_json
     end
   end
@@ -1766,9 +2230,7 @@ In Rails, HTTP request tests would go into the `spec/requests` group. You may wa
 
 ```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, file_path: /spec\/api/
 end
 ```
 
@@ -1799,7 +2261,11 @@ end
 
 ## Reloading API Changes in Development
 
-### Rails 3.x
+### Reloading in Rack Applications
+
+Use [grape-reload](https://github.com/AlexYankee/grape-reload).
+
+### Reloading in Rails Applications
 
 Add API paths to `config/application.rb`.