grape 1.1.0 → 1.7.1

data/README.md

@@ -1,12 +1,10 @@
 ![grape logo](grape.png)
 
 [![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)
+[![Build Status](https://github.com/ruby-grape/grape/workflows/test/badge.svg?branch=master)](https://github.com/ruby-grape/grape/actions)
 [![Code Climate](https://codeclimate.com/github/ruby-grape/grape.svg)](https://codeclimate.com/github/ruby-grape/grape)
 [![Coverage Status](https://coveralls.io/repos/github/ruby-grape/grape/badge.svg?branch=master)](https://coveralls.io/github/ruby-grape/grape?branch=master)
-[![Inline docs](http://inch-ci.org/github/ruby-grape/grape.svg)](http://inch-ci.org/github/ruby-grape/grape)
-[![git.legal](https://git.legal/projects/1364/badge.svg "Number of libraries approved")](https://git.legal/projects/1364)
+[![Inline docs](https://inch-ci.org/github/ruby-grape/grape.svg)](https://inch-ci.org/github/ruby-grape/grape)
 [![Join the chat at https://gitter.im/ruby-grape/grape](https://badges.gitter.im/ruby-grape/grape.svg)](https://gitter.im/ruby-grape/grape?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 ## Table of Contents
@@ -14,62 +12,77 @@
 - [What is Grape?](#what-is-grape)
 - [Stable Release](#stable-release)
 - [Project Resources](#project-resources)
+- [Grape for Enterprise](#grape-for-enterprise)
 - [Installation](#installation)
 - [Basic Usage](#basic-usage)
 - [Mounting](#mounting)
+  - [All](#all)
   - [Rack](#rack)
   - [ActiveRecord without Rails](#activerecord-without-rails)
+    - [Rails 4](#rails-4)
+    - [Rails 5+](#rails-5)
   - [Alongside Sinatra (or other frameworks)](#alongside-sinatra-or-other-frameworks)
   - [Rails](#rails)
+    - [Rails < 5.2](#rails--52)
+    - [Rails 6.0](#rails-60)
   - [Modules](#modules)
+- [Remounting](#remounting)
+  - [Mount Configuration](#mount-configuration)
 - [Versioning](#versioning)
   - [Path](#path)
   - [Header](#header)
   - [Accept-Version Header](#accept-version-header)
   - [Param](#param)
 - [Describing Methods](#describing-methods)
+- [Configuration](#configuration)
 - [Parameters](#parameters)
   - [Params Class](#params-class)
   - [Declared](#declared)
   - [Include Parent Namespaces](#include-parent-namespaces)
   - [Include Missing](#include-missing)
+  - [Evaluate Given](#evaluate-given)
 - [Parameter Validation and Coercion](#parameter-validation-and-coercion)
   - [Supported Parameter Types](#supported-parameter-types)
   - [Integer/Fixnum and Coercions](#integerfixnum-and-coercions)
   - [Custom Types and Coercions](#custom-types-and-coercions)
   - [Multipart File Parameters](#multipart-file-parameters)
-  - [First-Class `JSON` Types](#first-class-json-types)
+  - [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)
   - [Group Options](#group-options)
-  - [Alias](#alias)
+  - [Renaming](#renaming)
   - [Built-in Validators](#built-in-validators)
-    - [`allow_blank`](#allow_blank)
-    - [`values`](#values)
-    - [`except_values`](#except_values)
-    - [`regexp`](#regexp)
-    - [`mutually_exclusive`](#mutually_exclusive)
-    - [`exactly_one_of`](#exactly_one_of)
-    - [`at_least_one_of`](#at_least_one_of)
-    - [`all_or_none_of`](#all_or_none_of)
-    - [Nested `mutually_exclusive`, `exactly_one_of`, `at_least_one_of`, `all_or_none_of`](#nested-mutually_exclusive-exactly_one_of-at_least_one_of-all_or_none_of)
+    - [allow_blank](#allow_blank)
+    - [values](#values)
+    - [except_values](#except_values)
+    - [same_as](#same_as)
+    - [regexp](#regexp)
+    - [mutually_exclusive](#mutually_exclusive)
+    - [exactly_one_of](#exactly_one_of)
+    - [at_least_one_of](#at_least_one_of)
+    - [all_or_none_of](#all_or_none_of)
+    - [Nested mutually_exclusive, exactly_one_of, at_least_one_of, all_or_none_of](#nested-mutually_exclusive-exactly_one_of-at_least_one_of-all_or_none_of)
   - [Namespace Validation and Coercion](#namespace-validation-and-coercion)
   - [Custom Validators](#custom-validators)
   - [Validation Errors](#validation-errors)
   - [I18n](#i18n)
   - [Custom Validation messages](#custom-validation-messages)
-    - [`presence`, `allow_blank`, `values`, `regexp`](#presence-allow_blank-values-regexp)
-    - [`all_or_none_of`](#all_or_none_of-1)
-    - [`mutually_exclusive`](#mutually_exclusive-1)
-    - [`exactly_one_of`](#exactly_one_of-1)
-    - [`at_least_one_of`](#at_least_one_of-1)
-    - [`Coerce`](#coerce)
-    - [`With Lambdas`](#with-lambdas)
-    - [`Pass symbols for i18n translations`](#pass-symbols-for-i18n-translations)
+    - [presence, allow_blank, values, regexp](#presence-allow_blank-values-regexp)
+    - [same_as](#same_as-1)
+    - [all_or_none_of](#all_or_none_of-1)
+    - [mutually_exclusive](#mutually_exclusive-1)
+    - [exactly_one_of](#exactly_one_of-1)
+    - [at_least_one_of](#at_least_one_of-1)
+    - [Coerce](#coerce)
+    - [With Lambdas](#with-lambdas)
+    - [Pass symbols for i18n translations](#pass-symbols-for-i18n-translations)
     - [Overriding Attribute Names](#overriding-attribute-names)
     - [With Default](#with-default)
 - [Headers](#headers)
+  - [Request](#request)
+    - [Header Case Handling](#header-case-handling)
+  - [Response](#response)
 - [Routes](#routes)
 - [Helpers](#helpers)
 - [Path Helpers](#path-helpers)
@@ -105,7 +118,7 @@
   - [Register custom middleware for authentication](#register-custom-middleware-for-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)
+- [Before, After and Finally](#before-after-and-finally)
 - [Anchoring](#anchoring)
 - [Using Custom Middleware](#using-custom-middleware)
   - [Grape Middleware](#grape-middleware)
@@ -132,6 +145,7 @@
     - [format_response.grape](#format_responsegrape)
   - [Monitoring Products](#monitoring-products)
 - [Contributing to Grape](#contributing-to-grape)
+- [Security](#security)
 - [License](#license)
 - [Copyright](#copyright)
 
@@ -145,7 +159,7 @@ content negotiation, versioning and much more.
 
 ## Stable Release
 
-You're reading the documentation for the stable release of Grape, **1.1.0**.
+You're reading the documentation for the stable release of Grape, 1.7.1.
 Please read [UPGRADING](UPGRADING.md) when upgrading from a previous version.
 
 ## Project Resources
@@ -155,17 +169,19 @@ Please read [UPGRADING](UPGRADING.md) when upgrading from a previous version.
 * Need help? Try [Grape Google Group](http://groups.google.com/group/ruby-grape) or [Gitter](https://gitter.im/ruby-grape/grape)
 * [Follow us on Twitter](https://twitter.com/grapeframework)
 
-## Installation
+## Grape for Enterprise
+
+Available as part of the Tidelift Subscription.
 
-Grape is available as a gem, to install it just install the gem:
+The maintainers of Grape are working with Tidelift to deliver commercial support and maintenance. Save time, reduce risk, and improve code health, while paying the maintainers of Grape. Click [here](https://tidelift.com/subscription/request-a-demo?utm_source=rubygems-grape&utm_medium=referral&utm_campaign=enterprise) for more details.
 
-    gem install grape
+## Installation
 
-If you're using Bundler, add the gem to Gemfile.
+Ruby 2.4 or newer is required.
 
-    gem 'grape'
+Grape is available as a gem, to install it run:
 
-Run `bundle install`.
+    bundle add grape
 
 ## Basic Usage
 
@@ -204,7 +220,7 @@ module Twitter
 
       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
@@ -252,6 +268,17 @@ end
 
 ## Mounting
 
+### All
+
+
+By default Grape will compile the routes on the first route, it is possible to pre-load routes using the `compile!` method.
+
+```ruby
+Twitter::API.compile!
+```
+
+This can be added to your `config.ru` (if using rackup), `application.rb` (if using rails), or any file that loads your server.
+
 ### Rack
 
 The above sample creates a Rack application that can be run from a rackup `config.ru` file
@@ -261,6 +288,13 @@ with `rackup`:
 run Twitter::API
 ```
 
+(With pre-loading you can use)
+
+```ruby
+Twitter::API.compile!
+run Twitter::API
+```
+
 And would respond to the following routes:
 
     GET /api/statuses/public_timeline
@@ -277,13 +311,21 @@ Grape will also automatically respond to HEAD and OPTIONS for all GET, and just
 If you want to use ActiveRecord within Grape, you will need to make sure that ActiveRecord's connection pool
 is handled correctly.
 
+#### Rails 4
+
 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
+#### Rails 5+
+
+Use [otr-activerecord](https://github.com/jhollinger/otr-activerecord) as follows:
+
+```ruby
+use OTR::ActiveRecord::ConnectionManagement
 ```
 
 ### Alongside Sinatra (or other frameworks)
@@ -310,13 +352,24 @@ class Web < Sinatra::Base
 end
 
 use Rack::Session::Cookie
-run Rack::Cascade.new [API, Web]
+run Rack::Cascade.new [Web, API]
 ```
 
+Note that order of loading apps using `Rack::Cascade` matters. The grape application must be last if you want to raise custom 404 errors from grape (such as `error!('Not Found',404)`). If the grape application is not last and returns 404 or 405 response, [cascade utilizes that as a signal to try the next app](https://www.rubydoc.info/gems/rack/Rack/Cascade). This may lead to undesirable behavior showing the [wrong 404 page from the wrong app](https://github.com/ruby-grape/grape/issues/1515).
+
+
 ### Rails
 
 Place API files into `app/api`. Rails expects a subdirectory that matches the name of the Ruby module and a file name that matches the name of the class. In our example, the file name location and directory for `Twitter::API` should be `app/api/twitter/api.rb`.
 
+Modify `config/routes`:
+
+```ruby
+mount Twitter::API => '/'
+```
+
+#### Rails < 5.2
+
 Modify `application.rb`:
 
 ```ruby
@@ -324,14 +377,18 @@ config.paths.add File.join('app', 'api'), glob: File.join('**', '*.rb')
 config.autoload_paths += Dir[Rails.root.join('app', 'api', '*')]
 ```
 
-Modify `config/routes`:
+See [below](#reloading-api-changes-in-development) for additional code that enables reloading of API changes in development.
+
+#### Rails 6.0
+
+For Rails versions greater than 6.0.0.beta2, `Zeitwerk` autoloader is the default for CRuby. By default `Zeitwerk` inflects `api` as `Api` instead of `API`. To make our example work, you need to uncomment the lines at the bottom of `config/initializers/inflections.rb`, and add `API` as an acronym:
 
 ```ruby
-mount Twitter::API => '/'
+ActiveSupport::Inflector.inflections(:en) do |inflect|
+  inflect.acronym 'API'
+end
 ```
 
-See [below](#reloading-api-changes-in-development) for additional code that enables reloading of API changes in development.
-
 ### Modules
 
 You can mount multiple API implementations inside another one. These don't have to be
@@ -365,6 +422,131 @@ class Twitter::API < Grape::API
 end
 ```
 
+## Remounting
+
+You can mount the same endpoints in two different locations.
+
+```ruby
+class Voting::API < Grape::API
+  namespace 'votes' do
+    get do
+      # Your logic
+    end
+
+    post do
+      # Your logic
+    end
+  end
+end
+
+class Post::API < Grape::API
+  mount Voting::API
+end
+
+class Comment::API < Grape::API
+  mount Voting::API
+end
+```
+
+Assuming that the post and comment endpoints are mounted in `/posts` and `/comments`, you should now be able to do `get /posts/votes`, `post /posts/votes`, `get /comments/votes` and `post /comments/votes`.
+
+### Mount Configuration
+
+You can configure remountable endpoints to change how they behave according to where they are mounted.
+
+```ruby
+class Voting::API < Grape::API
+  namespace 'votes' do
+    desc "Vote for your #{configuration[:votable]}"
+    get do
+      # Your logic
+    end
+  end
+end
+
+class Post::API < Grape::API
+  mount Voting::API, with: { votable: 'posts' }
+end
+
+class Comment::API < Grape::API
+  mount Voting::API, with: { votable: 'comments' }
+end
+```
+
+Note that if you're passing a hash as the first parameter to `mount`, you will need to explicitly put `()` around parameters:
+```ruby
+# good
+mount({ ::Some::Api => '/some/api' }, with: { condition: true })
+
+# bad
+mount ::Some::Api => '/some/api', with: { condition: true }
+```
+
+You can access `configuration` on the class (to use as dynamic attributes), inside blocks (like namespace)
+
+If you want logic happening given on an `configuration`, you can use the helper `given`.
+
+```ruby
+class ConditionalEndpoint::API < Grape::API
+  given configuration[:some_setting] do
+    get 'mount_this_endpoint_conditionally' do
+      configuration[:configurable_response]
+    end
+  end
+end
+```
+
+If you want a block of logic running every time an endpoint is mounted (within which you can access the `configuration` Hash)
+
+
+```ruby
+class ConditionalEndpoint::API < Grape::API
+  mounted do
+    YourLogger.info "This API was mounted at: #{Time.now}"
+
+    get configuration[:endpoint_name] do
+      configuration[:configurable_response]
+    end
+  end
+end
+```
+
+More complex results can be achieved by using `mounted` as an expression within which the `configuration` is already evaluated as a Hash.
+
+```ruby
+class ExpressionEndpointAPI < Grape::API
+  get(mounted { configuration[:route_name] || 'default_name' }) do
+    # some logic
+  end
+end
+```
+
+```ruby
+class BasicAPI < Grape::API
+  desc 'Statuses index' do
+    params: mounted { configuration[:entity] || API::Entities::Status }.documentation
+  end
+  params do
+    requires :all, using: mounted { configuration[:entity] || API::Entities::Status }.documentation
+  end
+  get '/statuses' do
+    statuses = Status.all
+    type = current_user.admin? ? :full : :default
+    present statuses, with: mounted { configuration[:entity] || API::Entities::Status }, type: type
+  end
+end
+
+class V1 < Grape::API
+  version 'v1'
+  mount BasicAPI, with: { entity: mounted { configuration[:entity] || API::Entities::Status } }
+end
+
+class V2 < Grape::API
+  version 'v2'
+  mount BasicAPI, with: { entity: mounted { configuration[:entity] || API::Entities::V2::Status } }
+end
+```
+
 ## Versioning
 
 There are four strategies in which clients can reach your API's endpoints: `:path`,
@@ -445,14 +627,18 @@ version 'v1', using: :param, parameter: 'v'
 
 ## Describing Methods
 
-You can add a description to API methods and namespaces.
+You can add a description to API methods and namespaces. The description would be used by [grape-swagger][grape-swagger] to generate swagger compliant documentation.
+
+Note: Description block is only for documentation and won't affects API behavior.
 
 ```ruby
 desc 'Returns your public timeline.' do
+  summary 'summary'
   detail 'more details'
   params  API::Entities::Status.documentation
   success API::Entities::Entity
   failure [[401, 'Unauthorized', 'Entities::Error']]
+  default { code: 500, message: 'InvalidRequest', model: Entities::Error }
   named 'My named route'
   headers XAuthToken: {
             description: 'Validates your identity',
@@ -462,7 +648,13 @@ desc 'Returns your public timeline.' do
             description: 'Not really needed',
             required: false
           }
-
+  hidden false
+  deprecated false
+  is_array true
+  nickname 'nickname'
+  produces ['application/json']
+  consumes ['application/json']
+  tags ['tag1', 'tag2']
 end
 get :public_timeline do
   Status.limit(20)
@@ -471,10 +663,48 @@ 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
+* `success`: (former entity) The `Entity` to be used to present the success response for this route.
+* `failure`: (former http_codes) A definition of the used failure HTTP Codes and Entities.
+* `default`: The definition and `Entity` used to present the default response for this route.
 * `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
+* Other options can be found in [grape-swagger][grape-swagger]
+
+[grape-swagger]: https://github.com/ruby-grape/grape-swagger
+
+## Configuration
+
+Use `Grape.configure` to set up global settings at load time.
+Currently the configurable settings are:
+
+* `param_builder`: Sets the [Parameter Builder](#parameters), defaults to `Grape::Extensions::ActiveSupport::HashWithIndifferentAccess::ParamBuilder`.
+
+To change a setting value make sure that at some point during load time the following code runs
+
+```ruby
+Grape.configure do |config|
+  config.setting = value
+end
+```
+
+For example, for the `param_builder`, the following code could run in an initializer:
+
+```ruby
+Grape.configure do |config|
+  config.param_builder = Grape::Extensions::Hashie::Mash::ParamBuilder
+end
+```
+
+You can also configure a single API:
+
+```ruby
+API.configure do |config|
+  config[key] = value
+end
+```
+
+This will be available inside the API with `configuration`, as if it were
+[mount configuration](#mount-configuration).
 
 ## Parameters
 
@@ -553,13 +783,21 @@ params do
 end
 ```
 
+Or globally with the [Configuration](#configuration) `Grape.configure.param_builder`.
+
 In the example above, `params["color"]` will return `nil` since `params` is a plain `Hash`.
 
 Available parameter builders are `Grape::Extensions::Hash::ParamBuilder`, `Grape::Extensions::ActiveSupport::HashWithIndifferentAccess::ParamBuilder` and `Grape::Extensions::Hashie::Mash::ParamBuilder`.
 
 ### 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. Consider the following API endpoint:
+Grape allows you to access only the parameters that have been declared by your `params` block. It will:
+
+  * Filter out the params that have been passed, but are not allowed.
+  * Include any optional params that are declared but not passed.
+  * Perform any parameter renaming on the resulting hash.
+
+Consider the following API endpoint:
 
 ````ruby
 format :json
@@ -592,9 +830,9 @@ Once we add parameters requirements, grape will start returning only the declare
 format :json
 
 params do
-  requires :user, type: Hash do
-    requires :first_name, type: String
-    requires :last_name, type: String
+  optional :user, type: Hash do
+    optional :first_name, type: String
+    optional :last_name, type: String
   end
 end
 
@@ -622,6 +860,44 @@ curl -X POST -H "Content-Type: application/json" localhost:9292/users/signup -d
 }
 ````
 
+Missing params that are declared as type `Hash` or `Array` will be included.
+
+````ruby
+format :json
+
+params do
+  optional :user, type: Hash do
+    optional :first_name, type: String
+    optional :last_name, type: String
+  end
+  optional :widgets, type: Array
+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 '{}'
+````
+
+**Response**
+
+````json
+{
+  "declared_params": {
+    "user": {
+      "first_name": null,
+      "last_name": null
+    },
+    "widgets": []
+  }
+}
+````
+
 The returned hash is an `ActiveSupport::HashWithIndifferentAccess`.
 
 The `#declared` method is not available to `before` filters, as those are evaluated prior to parameter coercion.
@@ -680,8 +956,10 @@ By default `declared(params)` includes parameters that have `nil` values. If you
 format :json
 
 params do
-  requires :first_name, type: String
-  optional :last_name, type: String
+  requires :user, type: Hash do
+    requires :first_name, type: String
+    optional :last_name, type: String
+  end
 end
 
 post 'users/signup' do
@@ -712,8 +990,10 @@ curl -X POST -H "Content-Type: application/json" localhost:9292/users/signup -d
 ````json
 {
   "declared_params": {
-    "first_name": "first name",
-    "last_name": null
+    "user": {
+      "first_name": "first name",
+      "last_name": null
+    }
   }
 }
 ````
@@ -800,6 +1080,102 @@ curl -X POST -H "Content-Type: application/json" localhost:9292/users/signup -d
 }
 ````
 
+### Evaluate Given
+
+By default `declared(params)` will not evaluate `given` and return all parameters. Use `evaluate_given` to evaluate all `given` blocks and return only parameters that satisfy `given` conditions. Consider the following API:
+
+````ruby
+format :json
+
+params do
+  optional :child_id, type: Integer
+  given :child_id do
+    requires :father_id, type: Integer
+  end
+end
+
+post 'child' do
+  { 'declared_params' => declared(params, evaluate_given: true) }
+end
+````
+
+**Request**
+
+````bash
+curl -X POST -H "Content-Type: application/json" localhost:9292/child -d '{"father_id": 1}'
+````
+
+**Response with evaluate_given:false**
+
+````json
+{
+  "declared_params": {
+    "child_id": null,
+    "father_id": 1
+  }
+}
+````
+
+**Response with evaluate_given:true**
+
+````json
+{
+  "declared_params": {
+    "child_id": null
+  }
+}
+````
+
+It also works on nested hashes:
+
+````ruby
+format :json
+
+params do
+  requires :child, type: Hash do
+    optional :child_id, type: Integer
+    given :child_id do
+      requires :father_id, type: Integer
+    end
+  end
+end
+
+post 'child' do
+  { 'declared_params' => declared(params, evaluate_given: true) }
+end
+````
+
+**Request**
+
+````bash
+curl -X POST -H "Content-Type: application/json" localhost:9292/child -d '{"child": {"father_id": 1}}'
+````
+
+**Response with evaluate_given:false**
+
+````json
+{
+  "declared_params": {
+    "child": {
+      "child_id": null,
+      "father_id": 1
+    }
+  }
+}
+````
+
+**Response with evaluate_given:true**
+
+````json
+{
+  "declared_params": {
+    "child": {
+      "child_id": null
+    }
+  }
+}
+````
+
 ## Parameter Validation and Coercion
 
 You can define validations and coercion options for your parameters using a `params` block.
@@ -834,13 +1210,13 @@ params do
 end
 ```
 
-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.
-
 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.
 
+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
   optional :color, type: String, default: 'blue', values: ['red', 'green']
@@ -900,7 +1276,8 @@ Aside from the default set of supported types listed above, any class can be
 used as a type as 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.,
+type, or return an instance of `Grape::Types::InvalidValue` which optionally
+accepts a message to be returned in the response.
 
 ```ruby
 class Color
@@ -910,8 +1287,9 @@ class Color
   end
 
   def self.parse(value)
-    fail 'Invalid color' unless %w(blue red green).include?(value)
-    new(value)
+    return new(value) if %w[blue red green]).include?(value)
+
+    Grape::Types::InvalidValue.new('Unsupported color')
   end
 end
 
@@ -934,7 +1312,7 @@ parameter, and the return value must match the given `type`.
 
 ```ruby
 params do
-  requires :passwd, type: String, coerce_with: Base64.method(:decode)
+  requires :passwd, type: String, coerce_with: Base64.method(:decode64)
   requires :loud_color, type: Color, coerce_with: ->(c) { Color.parse(c.downcase) }
 
   requires :obj, type: Hash, coerce_with: JSON do
@@ -943,6 +1321,7 @@ params do
   end
 end
 ```
+Note that, a `nil` value will call the custom coercion method, while a missing parameter will not.
 
 Example of use of `coerce_with` with a lambda (a class with a `parse` method could also have been used)
 It will parse a string and return an Array of Integers, matching the `Array[Integer]` `type`.
@@ -1109,6 +1488,18 @@ params do
 end
 ```
 
+You can rename parameters:
+
+```ruby
+params do
+  optional :category, as: :type
+  given type: ->(val) { val == 'foo' } do
+    requires :description
+  end
+end
+```
+
+Note: param in `given` should be the renamed one. In the example, it should be `type`, not `category`.
 
 ### Group Options
 
@@ -1137,9 +1528,9 @@ params do
 end
 ```
 
-### Alias
+### Renaming
 
-You can set an alias for parameters using `as`, which can be useful when refactoring existing APIs:
+You can rename parameters using `as`, which can be useful when refactoring existing APIs:
 
 ```ruby
 resource :users do
@@ -1153,7 +1544,7 @@ resource :users do
 end
 ```
 
-The value passed to `as` will be the key when calling `params` or `declared(params)`.
+The value passed to `as` will be the key when calling `declared(params)`.
 
 ### Built-in Validators
 
@@ -1197,6 +1588,15 @@ params do
 end
 ```
 
+Note endless ranges are also supported with ActiveSupport >= 6.0, but they require that the type be provided.
+
+```ruby
+params do
+  requires :minimum, type: Integer, values: 10..
+  optional :maximum, type: Integer, values: ..10 
+end
+```
+
 Note that *both* range endpoints have to be a `#kind_of?` your `:type` option (if you don't supply the `:type` option, it will be guessed to be equal to the class of the range's first endpoint). So the following is invalid:
 
 ```ruby
@@ -1232,6 +1632,14 @@ end
 
 While Procs are convenient for single cases, consider using [Custom Validators](#custom-validators) in cases where a validation is used more than once.
 
+Note that [allow_blank](#allow_blank) validator applies while using `:values`. In the following example the absence of `:allow_blank` does not prevent `:state` from receiving blank values because `:allow_blank` defaults to `true`.
+
+```ruby
+params do
+  requires :state, type: Symbol, values: [:active, :inactive]
+end
+```
+
 #### `except_values`
 
 Parameters can be restricted from having a specific set of values with the `:except_values` option.
@@ -1248,6 +1656,17 @@ params do
 end
 ```
 
+#### `same_as`
+
+A `same_as` option can be given to ensure that values of parameters match.
+
+```ruby
+params do
+  requires :password
+  requires :password_confirmation, same_as: :password
+end
+```
+
 #### `regexp`
 
 Parameters can be restricted to match a specific regular expression with the `:regexp` option. If the value
@@ -1423,10 +1842,10 @@ end
 ### Custom Validators
 
 ```ruby
-class AlphaNumeric < Grape::Validations::Base
+class AlphaNumeric < Grape::Validations::Validators::Base
   def validate_param!(attr_name, params)
     unless params[attr_name] =~ /\A[[:alnum:]]+\z/
-      fail Grape::Exceptions::Validation, params: [@scope.full_name(attr_name)], message: 'must consist of alpha-numeric characters'
+      raise Grape::Exceptions::Validation.new params: [@scope.full_name(attr_name)], message: 'must consist of alpha-numeric characters'
     end
   end
 end
@@ -1441,10 +1860,10 @@ end
 You can also create custom classes that take parameters.
 
 ```ruby
-class Length < Grape::Validations::Base
+class Length < Grape::Validations::Validators::Base
   def validate_param!(attr_name, params)
     unless params[attr_name].length <= @option
-      fail Grape::Exceptions::Validation, params: [@scope.full_name(attr_name)], message: "must be at the most #{@option} characters long"
+      raise Grape::Exceptions::Validation.new params: [@scope.full_name(attr_name)], message: "must be at the most #{@option} characters long"
     end
   end
 end
@@ -1459,7 +1878,7 @@ end
 You can also create custom validation that use request to validate the attribute. For example if you want to have parameters that are available to only admins, you can do the following.
 
 ```ruby
-class Admin < Grape::Validations::Base
+class Admin < Grape::Validations::Validators::Base
   def validate(request)
     # return if the param we are checking was not in request
     # @attrs is a list containing the attribute we are currently validating
@@ -1470,7 +1889,7 @@ class Admin < Grape::Validations::Base
     return unless @option
     # check if user is admin or not
     # as an example get a token from request and check if it's admin or not
-    fail Grape::Exceptions::Validation, params: @attrs, message: 'Can not set admin-only field.' unless request.headers['X-Access-Token'] == 'admin'
+    raise Grape::Exceptions::Validation.new params: @attrs, message: 'Can not set admin-only field.' unless request.headers['X-Access-Token'] == 'admin'
   end
 end
 ```
@@ -1485,7 +1904,7 @@ params do
 end
 ```
 
-Every validation will have it's own instance of the validator, which means that the validator can have a state.
+Every validation will have its own instance of the validator, which means that the validator can have a state.
 
 ### Validation Errors
 
@@ -1546,6 +1965,8 @@ end
 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.
 
+In case your app enforces available locales only and :en is not included in your available locales, Grape cannot fall back to English and will return the translation key for the error message. To avoid this behaviour, either provide a translation for your default locale or add :en to your available locales.
+
 ### Custom Validation messages
 
 Grape supports custom validation messages for parameter-related and coerce-related error messages.
@@ -1558,6 +1979,15 @@ params do
 end
 ```
 
+#### `same_as`
+
+```ruby
+params do
+  requires :password
+  requires :password_confirmation, same_as: { value: :password, message: 'not match' }
+end
+```
+
 #### `all_or_none_of`
 
 ```ruby
@@ -1587,7 +2017,7 @@ params do
   optional :beer
   optional :wine
   optional :juice
-  exactly_one_of :beer, :wine, :juice, message: {exactly_one: "are missing, exactly one parameter is required", mutual_exclusion: "are mutually exclusive, exactly one parameter is required"}
+  exactly_one_of :beer, :wine, :juice, message: { exactly_one: "are missing, exactly one parameter is required", mutual_exclusion: "are mutually exclusive, exactly one parameter is required" }
 end
 ```
 
@@ -1606,7 +2036,7 @@ end
 
 ```ruby
 params do
-  requires :int, type: {value: Integer, message: "type cast is invalid" }
+  requires :int, type: { value: Integer, message: "type cast is invalid" }
 end
 ```
 
@@ -1668,6 +2098,7 @@ end
 
 ## Headers
 
+### Request
 Request headers are available through the `headers` helper or from `env` in their original form.
 
 ```ruby
@@ -1682,13 +2113,30 @@ get do
 end
 ```
 
+#### Header Case Handling
+
+The above example may have been requested as follows:
+
+``` shell
+curl -H "secret_PassWord: swordfish" ...
+```
+
+The header name will have been normalized for you.
+
+- In the `header` helper names will be coerced into a capitalized kebab case.
+- In the `env` collection they appear in all uppercase, in snake case, and prefixed with 'HTTP_'.
+
+The header name will have been normalized per HTTP standards defined in [RFC2616 Section 4.2](https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2) regardless of what is being sent by a client.
+
+### Response
+
 You can set a response header with `header` inside an API.
 
 ```ruby
 header 'X-Robots-Tag', 'noindex'
 ```
 
-When raising `error!`, pass additional headers as arguments.
+When raising `error!`, pass additional headers as arguments. Additional headers will be merged with headers set before `error!` call.
 
 ```ruby
 error! 'Unauthorized', 401, 'X-Error-Detail' => 'Invalid token.'
@@ -1696,6 +2144,56 @@ error! 'Unauthorized', 401, 'X-Error-Detail' => 'Invalid token.'
 
 ## Routes
 
+To define routes you can use the `route` method or the shorthands for the HTTP verbs. To define a route that accepts any route set to `:any`.
+Parts of the path that are denoted with a colon will be interpreted as route parameters.
+
+```ruby
+route :get, 'status' do
+end
+
+# is the same as
+
+get 'status' do
+end
+
+# is the same as
+
+get :status do
+end
+
+# is NOT the same as
+
+get ':status' do # this makes params[:status] available
+end
+
+# This will make both params[:status_id] and params[:id] available
+
+get 'statuses/:status_id/reviews/:id' do
+end
+```
+
+To declare a namespace that prefixes all routes within, use the `namespace` method. `group`, `resource`, `resources` and `segment` are aliases to this method. Any endpoints within will share their parent context as well as any configuration done in the namespace context.
+
+The `route_param` method is a convenient method for defining a parameter route segment. If you define a type, it will add a validation for this parameter.
+
+```ruby
+route_param :id, type: Integer do
+  get 'status' do
+  end
+end
+
+# is the same as
+
+namespace ':id' do
+  params do
+    requires :id, type: Integer
+  end
+
+  get 'status' do
+  end
+end
+```
+
 Optionally, you can define requirements for your named route parameters using regular
 expressions on namespace or endpoint. The route will match only if all requirements are met.
 
@@ -1850,6 +2348,18 @@ params do
 end
 ```
 
+If documentation isn't needed (for instance, it is an internal API), documentation can be disabled.
+
+```ruby
+class API < Grape::API
+  do_not_document!
+
+  # endpoints...
+end
+```
+
+In this case, Grape won't create objects related to documentation which are retained in RAM forever.
+
 ## Cookies
 
 You can set, get and delete your cookies very simply using `cookies` method.
@@ -2028,6 +2538,12 @@ instead of a message.
 error!({ error: 'unexpected error', detail: 'missing widget' }, 500)
 ```
 
+You can set additional headers for the response. They will be merged with headers set before `error!` call.
+
+```ruby
+error!('Something went wrong', 500, 'X-Error-Detail' => 'Invalid token.')
+```
+
 You can present documented errors with a Grape entity using the the [grape-entity](https://github.com/ruby-grape/grape-entity) gem.
 
 ```ruby
@@ -2182,7 +2698,7 @@ You can also rescue all exceptions with a code block and handle the Rack respons
 ```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' })
   end
 end
 ```
@@ -2253,9 +2769,9 @@ class Twitter::API < Grape::API
 end
 ```
 
-The `rescue_from` block must return a `Rack::Response` object, call `error!` or re-raise an exception.
+The `rescue_from` handler must return a `Rack::Response` object, call `error!`, or raise an exception (either the original exception or another custom one). The exception raised in `rescue_from` will be handled outside Grape. For example, if you mount Grape in Rails, the exception will be handle by [Rails Action Controller](https://guides.rubyonrails.org/action_controller_overview.html#rescue).
 
-The `with` keyword is available as `rescue_from` options, it can be passed method name or Proc object.
+Alternately, use the `with` option in `rescue_from` to specify a method or a `proc`.
 
 ```ruby
 class Twitter::API < Grape::API
@@ -2271,6 +2787,17 @@ class Twitter::API < Grape::API
 end
 ```
 
+Inside the `rescue_from` block, the environment of the original controller method(`.self` receiver) is accessible through the `#context` method.
+
+```ruby
+class Twitter::API < Grape::API
+  rescue_from :all do |e|
+    user_id = context.params[:user_id]
+    error!("error for #{user_id}")
+  end
+end
+```
+
 #### Rescuing exceptions inside namespaces
 
 You could put `rescue_from` clauses inside a namespace and they will take precedence over ones
@@ -2293,7 +2820,7 @@ class Twitter::API < Grape::API
 end
 ```
 
-Here `'inner'` will be result of handling occured `ArgumentError`.
+Here `'inner'` will be result of handling occurred `ArgumentError`.
 
 #### Unrescuable Exceptions
 
@@ -2824,17 +3351,30 @@ end
 
 Use `body false` to return `204 No Content` without any data or content-type.
 
-You can also set the response to a file with `file`.
+If you want to empty the body with an HTTP status code other than `204 No Content`, you can override the status code after specifying `body false` as follows
+
+```ruby
+class API < Grape::API
+  get '/' do
+    body false
+    status 304
+  end
+end
+```
+
+You can also set the response to a file with `sendfile`. This works with the
+[Rack::Sendfile](https://www.rubydoc.info/gems/rack/Rack/Sendfile) middleware to optimally send
+the file through your web server software.
 
 ```ruby
 class API < Grape::API
   get '/' do
-    file '/path/to/file'
+    sendfile '/path/to/file'
   end
 end
 ```
 
-If you want a file to be streamed using Rack::Chunked, use `stream`.
+To stream a file in chunks use `stream`
 
 ```ruby
 class API < Grape::API
@@ -2844,6 +3384,26 @@ class API < Grape::API
 end
 ```
 
+If you want to stream non-file data use the `stream` method and a `Stream` object.
+This is an object that responds to `each` and yields for each chunk to send to the client.
+Each chunk will be sent as it is yielded instead of waiting for all of the content to be available.
+
+```ruby
+class MyStream
+  def each
+    yield 'part 1'
+    yield 'part 2'
+    yield 'part 3'
+  end
+end
+
+class API < Grape::API
+  get '/' do
+    stream MyStream.new
+  end
+end
+```
+
 ## Authentication
 
 ### Basic and Digest Auth
@@ -2855,14 +3415,21 @@ applies to the current namespace and any children, but not parents.
 ```ruby
 http_basic do |username, password|
   # verify user's password here
-  { 'test' => 'password1' }[username] == password
+  # IMPORTANT: make sure you use a comparison method which isn't prone to a timing attack
 end
 ```
 
+Digest auth supports clear-text passwords and password hashes.
+
 ```ruby
 http_digest({ realm: 'Test Api', opaque: 'app secret' }) do |username|
   # lookup the user's password here
-  { 'user1' => 'password1' }[username]
+end
+```
+
+```ruby
+http_digest(realm: { realm: 'Test Api', opaque: 'app secret', passwords_hashed: true }) do |username|
+  # lookup the user's password hash here
 end
 ```
 
@@ -2893,7 +3460,9 @@ end
 
 ```
 
-Use [warden-oauth2](https://github.com/opperator/warden-oauth2) or [rack-oauth2](https://github.com/nov/rack-oauth2) for OAuth2 support.
+Use [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper), [warden-oauth2](https://github.com/opperator/warden-oauth2) or [rack-oauth2](https://github.com/nov/rack-oauth2) for OAuth2 support.
+
+You can access the controller params, headers, and helpers through the context with the `#context` method inside any auth middleware inherited from `Grape::Middleware::Auth::Base`.
 
 ## Describing and Inspecting an API
 
@@ -2962,19 +3531,22 @@ class ApiLogger < Grape::Middleware::Base
 end
 ```
 
-## Before and After
+## Before, After and Finally
 
 Blocks can be executed before or after every API call, using `before`, `after`,
 `before_validation` and `after_validation`.
+If the API fails the `after` call will not be triggered, if you need code to execute for sure
+use the `finally`.
 
 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`
+4. `after_validation` (upon successful validation)
+5. _the API call_ (upon successful validation)
+6. `after` (upon successful validation and API call)
+7. `finally` (always)
 
 Steps 4, 5 and 6 only happen if validation succeeds.
 
@@ -2994,6 +3566,14 @@ before do
 end
 ```
 
+You can ensure a block of code runs after every request (including failures) with `finally`:
+
+```ruby
+finally do
+  # this code will run after every request (successful or failed)
+end
+```
+
 **Namespaces**
 
 Callbacks apply to each API call within and below the current namespace:
@@ -3196,11 +3776,21 @@ class API < Grape::API
 end
 ```
 
+You can access the controller params, headers, and helpers through the context with the `#context` method inside any middleware inherited from `Grape::Middleware::Base`.
+
 ### 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.
 
+If you are using a custom application that is inherited from `Rails::Application` and need to insert a new middleware among the ones initiated via Rails, you will need to register it manually in your custom application class.
+
+```ruby
+class Company::Application < Rails::Application
+  config.middleware.insert_before(Rack::Attack, Middleware::ApiLogger)
+end
+```
+
 ### 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`.
@@ -3234,7 +3824,7 @@ Use `rack-test` and define your API as `app`.
 You can test a Grape API with RSpec by making HTTP requests and examining the response.
 
 ```ruby
-require 'spec_helper'
+
 
 describe Twitter::API do
   include Rack::Test::Methods
@@ -3504,6 +4094,8 @@ Grape integrates with following third-party tools:
 * **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/)
 * **[AppSignal](https://www.appsignal.com)** - [appsignal-ruby](https://github.com/appsignal/appsignal-ruby) gem, [documentation](http://docs.appsignal.com/getting-started/supported-frameworks.html#grape)
+* **[ElasticAPM](https://www.elastic.co/products/apm)** - [elastic-apm](https://github.com/elastic/apm-agent-ruby) gem, [documentation](https://www.elastic.co/guide/en/apm/agent/ruby/3.x/getting-started-rack.html#getting-started-grape)
+* **[Datadog APM](https://docs.datadoghq.com/tracing/)** - [ddtrace](https://github.com/datadog/dd-trace-rb) gem, [documentation](https://docs.datadoghq.com/tracing/setup_overview/setup/ruby/#grape)
 
 ## Contributing to Grape
 
@@ -3512,10 +4104,14 @@ features and discuss issues.
 
 See [CONTRIBUTING](CONTRIBUTING.md).
 
+## Security
+
+See [SECURITY](SECURITY.md) for details.
+
 ## License
 
-MIT License. See LICENSE for details.
+MIT License. See [LICENSE](LICENSE) for details.
 
 ## Copyright
 
-Copyright (c) 2010-2018 Michael Bleigh, Intridea Inc. and Contributors.
+Copyright (c) 2010-2020 Michael Bleigh, Intridea Inc. and Contributors.