grape 0.6.1 → 0.7.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    N2JkMzEwZGIyN2M4ZWVkMjczNmU1OTZiNTQzYTA3Yjc1YWI1MzRiNw==
+    NzU0ZDEzNjI0ZDhlMzg5M2YxOTMzMmU2NmUxMWIyZDYxMGM3ODBiNQ==
   data.tar.gz: !binary |-
-    ODE0MmI1YjY3YjZlNjdhOGY0ZGI1OTdjMWRhYmI3N2JiZjJmNWMwYg==
-!binary "U0hBNTEy":
+    NmMwYmIxODY2ZmI0YzY5MzljYTM0NWE5MDM4MzAwZDQ3M2Y4MmYwNg==
+SHA512:
   metadata.gz: !binary |-
-    NWYxMGEyMWE0NWE4ZTlkMjczMmY3ZjA1NGUwZjNhZmJlYjk3MGQ5NTE0NDk3
-    OGUyOWU5YmVhNzMwMWJkOTIxYjgwZmU0ODk1YWU4Yzc1ZTdkMWY4NTc0MDlh
-    ODQ4NjczZWRhMGVmMmQ1MDg3Njk5MjBjMTk5N2VjYmM0Y2ZiZDE=
+    ODgwYzYzMzlkNzJjMTgyYzkyMmQ3ZDhlNWEyNDRmMGNiZDMxZDI4NDIzZGRk
+    NzEwNjdjYjI0MzkzNzE1M2QwM2ExZGM2NDRlMmFlNDJlZWY3NjljMGMxN2Zm
+    OWNkMGM0ZGFkMDQwYzk1MDBlNDZkNjI4ZmJmZjM4M2Y3MmU4NDI=
   data.tar.gz: !binary |-
-    OTI1ZDU2ZDViNjc2YWE4MTczMThmN2I5ZGYwZGZlYmE0YjZlMDI3NjVlNTE5
-    NjcwOTRkNTg2NTgwODFhMTg3YjZkM2Y3NzYwYzkwNTYxMGEzMzU2NDBiYzBk
-    ZGJlYTRmMDEwNGJkNDc3YzNiMmUyM2IyMDUwMGM3MGFhMDhiYTg=
+    N2Y5Y2NhNWQxMjNmYmZmMzJhZDQyMzE2NDY1ODRlNjVhNDc2ZjQxNTE4NjRl
+    YzczZTk5NGUwZGQ1ZmJiNTUwNmQ5MTM1ZWVkNzA0M2JlNDZhNGVkM2MyNTM5
+    Zjg2MzhkNGI5YjMxNzRlNWUyZDg1YzA2NjY4MjdkMWE4MTU1N2Y=

data/.gitignore

@@ -35,4 +35,11 @@ tmp
 ## Rubinius
 .rbx
 
+## Bundler binstubs
+bin
+
+## ripper-tags and gem-ctags
+tags
+
 ## PROJECT::SPECIFIC
+.project

data/.rubocop.yml

@@ -1,6 +1,7 @@
 AllCops:
   Excludes:
     - vendor/**
+    - bin/**
 
 LineLength:
   Enabled: false
@@ -63,3 +64,7 @@ Blocks:
 WordArray:
   # %w vs. [ '', ... ]
   Enabled: false
+
+CyclomaticComplexity:
+  Enabled: false
+

data/.travis.yml

@@ -1,9 +1,9 @@
 language: ruby
 cache: bundler
+before_install:
+  - gem install bundler -v '= 1.5.1'
 rvm:
+  - 2.1.0
   - 2.0.0
   - 1.9.3
   - jruby-19mode
-  - rbx-19mode
-script:
- - "bundle exec rubocop"

data/CHANGELOG.md

@@ -1,5 +1,44 @@
-0.6.1
-=====
+0.7.0 (4/2/2013)
+=================
+
+#### Features
+* [#558](https://github.com/intridea/grape/pull/558): Support lambda-based values for params - [@wpschallenger](https://github.com/wpschallenger).
+* [#510](https://github.com/intridea/grape/pull/510): Support lambda-based default values for params - [@myitcv](https://github.com/myitcv).
+* [#511](https://github.com/intridea/grape/pull/511): Added `required` option for OAuth2 middleware - [@bcm](https://github.com/bcm).
+* [#520](https://github.com/intridea/grape/pull/520): Use `default_error_status` to specify the default status code returned from `error!` - [@salimane](https://github.com/salimane).
+* [#525](https://github.com/intridea/grape/pull/525): The default status code returned from `error!` has been changed from 403 to 500 - [@dblock](https://github.com/dblock).
+* [#526](https://github.com/intridea/grape/pull/526): Allowed specifying headers in `error!` - [@dblock](https://github.com/dblock).
+* [#527](https://github.com/intridea/grape/pull/527): The `before_validation` callback is now a distinct one - [@myitcv](https://github.com/myitcv).
+* [#530](https://github.com/intridea/grape/pull/530): Added ability to restrict `declared(params)` to the local endpoint with `include_parent_namespaces: false` - [@myitcv](https://github.com/myitcv).
+* [#531](https://github.com/intridea/grape/pull/531): Helpers are now available to auth middleware, executing in the context of the endpoint - [@joelvh](https://github.com/joelvh).
+* [#540](https://github.com/intridea/grape/pull/540): Ruby 2.1.0 is now supported - [@salimane](https://github.com/salimane).
+* [#544](https://github.com/intridea/grape/pull/544): The `rescue_from` keyword now handles subclasses of exceptions by default - [@xevix](https://github.com/xevix).
+* [#545](https://github.com/intridea/grape/pull/545): Added `type` (`Array` or `Hash`) support to `requires`, `optional` and `group` - [@bwalex](https://github.com/bwalex).
+* [#550](https://github.com/intridea/grape/pull/550): Added possibility to define reusable params - [@dm1try](https://github.com/dm1try).
+* [#560](https://github.com/intridea/grape/pull/560): Use `Grape::Entity` documentation to define required and optional parameters with `requires using:` - [@reynardmh](https://github.com/reynardmh).
+* [#572](https://github.com/intridea/grape/pull/572): Added `documentation` support to `requires`, `optional` and `group` parameters - [@johnallen3d](https://github.com/johnallen3d).
+
+#### Fixes
+
+* [#600](https://github.com/intridea/grape/pull/600): Don't use an `Entity` constant that is available in the namespace as presenter - [@fuksito](https://github.com/fuksito).
+* [#590](https://github.com/intridea/grape/pull/590): Fix issue where endpoint param of type `Integer` cannot set values array - [@xevix](https://github.com/xevix).
+* [#586](https://github.com/intridea/grape/pull/586): Do not repeat the same validation error messages - [@kiela](https://github.com/kiela).
+* [#508](https://github.com/intridea/grape/pull/508): Allow parameters, such as content encoding, in `content_type` - [@dm1try](https://github.com/dm1try).
+* [#492](https://github.com/intridea/grape/pull/492): Don't allow to have nil value when a param is required and has a list of allowed values - [@Antti](https://github.com/Antti).
+* [#495](https://github.com/intridea/grape/pull/495): Fixed `ParamsScope#params` for parameters nested inside arrays - [@asross](https://github.com/asross).
+* [#498](https://github.com/intridea/grape/pull/498): Dry'ed up options and headers logic, allow headers to be passed to OPTIONS requests - [@karlfreeman](https://github.com/karlfreeman).
+* [#500](https://github.com/intridea/grape/pull/500): Skip entity auto-detection when explicitely passed - [@yaneq](https://github.com/yaneq).
+* [#503](https://github.com/intridea/grape/pull/503): Calling declared(params) from child namespace fails to include parent namespace defined params - [@myitcv](https://github.com/myitcv).
+* [#512](https://github.com/intridea/grape/pull/512): Don't create `Grape::Request` multiple times - [@dblock](https://github.com/dblock).
+* [#538](https://github.com/intridea/grape/pull/538): Fixed default values for grouped params - [@dm1try](https://github.com/dm1try).
+* [#549](https://github.com/intridea/grape/pull/549): Fixed handling of invalid version headers to return 406 if a header cannot be parsed - [@bwalex](https://github.com/bwalex).
+* [#557](https://github.com/intridea/grape/pull/557): Pass `content_types` option to `Grape::Middleware::Error` to fix the content-type header for custom formats. - [@bernd](https://github.com/bernd).
+* [#585](https://github.com/intridea/grape/pull/585): Fix after boot thread-safety issue - [@etehtsea](https://github.com/etehtsea).
+* [#587](https://github.com/intridea/grape/pull/587): Fix oauth2 middleware compatibility with [draft-ietf-oauth-v2-31](http://tools.ietf.org/html/draft-ietf-oauth-v2-31) spec - [@etehtsea](https://github.com/etehtsea).
+* [#610](https://github.com/intridea/grape/pull/610): Fixed group keyword was not working with type parameter - [@klausmeyer](https://github.com/klausmeyer/).
+
+0.6.1 (10/19/2013)
+==================
 
 #### Features
 
@@ -28,7 +67,7 @@
 * [#450](https://github.com/intridea/grape/pull/450): Added option to pass an exception handler lambda as an argument to `rescue_from` - [@robertopedroso](https://github.com/robertopedroso).
 * [#443](https://github.com/intridea/grape/pull/443): Let `requires` and `optional` take blocks that initialize new scopes - [@asross](https://github.com/asross).
 * [#452](https://github.com/intridea/grape/pull/452): Added `with` as a hash option to specify handlers for `rescue_from` and `error_formatter` [@robertopedroso](https://github.com/robertopedroso).
-* [#433](https://github.com/intridea/grape/issues/433), [#462](https://github.com/intridea/grape/issues/462): API change: validation errors are now collected and `Grape::Exceptions::ValidationErrors` is raised - [@stevschmid](https://github.com/stevschmid).
+* [#433](https://github.com/intridea/grape/issues/433), [#462](https://github.com/intridea/grape/issues/462): Validation errors are now collected and `Grape::Exceptions::ValidationErrors` is raised - [@stevschmid](https://github.com/stevschmid).
 
 #### Fixes
 

data/CONTRIBUTING.md

@@ -0,0 +1,118 @@
+Contributing to Grape
+=====================
+
+Grape is work of [hundreds of contributors](https://github.com/intridea/grape/graphs/contributors). You're encouraged to submit [pull requests](https://github.com/intridea/grape/pulls), [propose features and discuss issues](https://github.com/intridea/grape/issues). When in doubt, ask a question in the [Grape Google Group](http://groups.google.com/group/ruby-grape).
+
+#### Fork the Project
+
+Fork the [project on Github](https://github.com/intridea/grape) and check out your copy.
+
+```
+git clone https://github.com/contributor/grape.git
+cd grape
+git remote add upstream https://github.com/intridea/grape.git
+```
+
+#### Create a Topic Branch
+
+Make sure your fork is up-to-date and create a topic branch for your feature or bug fix.
+
+```
+git checkout master
+git pull upstream master
+git checkout -b my-feature-branch
+```
+
+#### Bundle Install and Test
+
+Ensure that you can build the project and run tests.
+
+```
+bundle install
+bundle exec rake
+```
+
+#### 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).
+
+We definitely appreciate pull requests that highlight or reproduce a problem, even without a fix.
+
+#### Write Code
+
+Implement your feature or bug fix.
+
+Ruby style is enforced with [Rubocop](https://github.com/bbatsov/rubocop), run `bundle exec rubocop` and fix any style issues highlighted.
+
+Make sure that `bundle exec rake` completes without errors.
+
+#### Write Documentation
+
+Document any external behavior in the [README](README.md).
+
+#### Update Changelog
+
+Add a line to [CHANGELOG](CHANGELOG.md) under *Next Release*. Make it look like every other line, including your name and link to your Github account.
+
+#### Commit Changes
+
+Make sure git knows your name and email address:
+
+```
+git config --global user.name "Your Name"
+git config --global user.email "contributor@example.com"
+```
+
+Writing good commit logs is important. A commit log should describe what changed and why.
+
+```
+git add ...
+git commit
+```
+
+#### Push
+
+```
+git push origin my-feature-branch
+```
+
+#### Make a Pull Request
+
+Go to https://github.com/contributor/grape and select your feature branch. Click the 'Pull Request' button and fill out the form. Pull requests are usually reviewed within a few days.
+
+#### Rebase
+
+If you've been working on a change for a while, rebase with upstream/master.
+
+```
+git fetch upstream
+git rebase upstream/master
+git push origin my-feature-branch -f
+```
+
+#### Update CHANGELOG Again
+
+Update the [CHANGELOG](CHANGELOG.md) with the pull request number. A typical entry looks as follows.
+
+```
+* [#123](https://github.com/intridea/grape/pull/123): Reticulated splines - [@contributor](https://github.com/contributor).
+```
+
+Amend your previous commit and force push the changes.
+
+```
+git commit --amend
+git push origin my-feature-branch -f
+```
+
+#### Check on Your Pull Request
+
+Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI. Everything should look green, otherwise fix issues and amend your commit as described above.
+
+#### Be Patient
+
+It's likely that your change will not be merged and that the nitpicky maintainers will ask you to do more, or fix seemingly benign problems. Hang on there!
+
+#### Thank You
+
+Please do know that we really appreciate and value your time and work. We love you, really.

data/Gemfile

@@ -10,11 +10,11 @@ group :development, :test do
   gem 'rb-fsevent'
   gem 'growl'
   gem 'json'
-  gem 'rspec'
-  gem 'rack-test', "~> 0.6.2", :require => "rack/test"
+  gem 'rspec', '~> 2.14.1'
+  gem 'rack-test', '~> 0.6.2', require: 'rack/test'
   gem 'github-markup'
   gem 'cookiejar'
   gem 'rack-contrib'
-  gem 'redcarpet', :platforms => :ruby
-  gem 'rubocop', '~> 0.14.1'
+  gem 'redcarpet', platforms: :ruby
+  gem 'rubocop', '~> 0.15.0'
 end

data/README.md

@@ -8,11 +8,11 @@ providing a simple DSL to easily develop RESTful APIs. It has built-in support
 for common conventions, including multiple formats, subdomain/prefix restriction,
 content negotiation, versioning and much more.
 
-[![Build Status](https://travis-ci.org/intridea/grape.png?branch=master)](http://travis-ci.org/intridea/grape) [![Code Climate](https://codeclimate.com/github/intridea/grape.png)](https://codeclimate.com/github/intridea/grape)
+[![Build Status](https://travis-ci.org/intridea/grape.png?branch=master)](http://travis-ci.org/intridea/grape) [![Code Climate](https://codeclimate.com/github/intridea/grape.png)](https://codeclimate.com/github/intridea/grape) [![Inline docs](http://inch-pages.github.io/github/intridea/grape.png)](http://inch-pages.github.io/github/intridea/grape) [![Dependency Status](https://www.versioneye.com/ruby/grape/0.6.1/badge.png)](https://www.versioneye.com/ruby/grape/0.6.1)
 
 ## Stable Release
 
-You're reading the documentation for the stable release of Grape, 0.6.1.
+You're reading the documentation for the stable release of Grape, 0.7.0.
 
 ## Project Resources
 
@@ -40,7 +40,6 @@ the context of recreating parts of the Twitter API.
 ```ruby
 module Twitter
   class API < Grape::API
-
     version 'v1', using: :header, vendor: 'twitter'
     format :json
 
@@ -55,7 +54,6 @@ module Twitter
     end
 
     resource :statuses do
-
       desc "Return a public timeline."
       get :public_timeline do
         Status.limit(20)
@@ -110,7 +108,6 @@ module Twitter
         authenticate!
         current_user.statuses.find(params[:id]).destroy
       end
-
     end
   end
 end
@@ -151,7 +148,7 @@ require 'grape'
 
 class API < Grape::API
   get :hello do
-    {hello: "world"}
+    { hello: "world" }
   end
 end
 
@@ -170,8 +167,8 @@ run Rack::Cascade.new [API, Web]
 Place API files into `app/api` and modify `application.rb`.
 
 ```ruby
-config.paths.add "app/api", glob: "**/*.rb"
-config.autoload_paths += Dir["#{Rails.root}/app/api/*"]
+config.paths.add File.join('app', 'api'), glob: File.join('**', '*.rb')
+config.autoload_paths += Dir[Rails.root.join('app', 'api', '*')]
 ```
 
 Modify `config/routes`:
@@ -232,6 +229,10 @@ supplied. This behavior is similar to routing in Rails. To circumvent this defau
 one could use the `:strict` option. When this option is set to `true`, a `406 Not Acceptable` error
 is returned when no correct `Accept` header is supplied.
 
+When an invalid `Accept` header is supplied, a `406 Not Acceptable` error is returned if the `:cascade`
+option is set to `false`. Otherwise a `404 Not Found` error is returned by Rack if no other route
+matches.
+
 ### Accept-Version Header
 
 ```ruby
@@ -289,7 +290,7 @@ get :public_timeline do
 end
 ```
 
-Parameters are automatically populated from the request body on POST and PUT for form input, JSON and
+Parameters are automatically populated from the request body on `POST` and `PUT` for form input, JSON and
 XML content-types.
 
 The request:
@@ -302,7 +303,7 @@ The Grape endpoint:
 
 ```ruby
 post '/statuses' do
-  Status.create!({ text: params[:text] })
+  Status.create!(text: params[:text])
 end
 ```
 
@@ -311,7 +312,7 @@ Multipart POSTs and PUTs are supported as well.
 The request:
 
 ```
-curl --form image_file=image.jpg http://localhost:9292/upload
+curl --form image_file=@image.jpg http://localhost:9292/upload
 ```
 
 The Grape endpoint:
@@ -322,6 +323,14 @@ post "upload" do
 end
 ```
 
+In the case of conflict between either of:
+
+* route string parameters
+* `GET`, `POST` and `PUT` parameters
+* the contents of the request body on `POST` and `PUT`
+
+route string parameters will have precedence.
+
 ## Parameter Validation and Coercion
 
 You can define validations and coercion options for your parameters using a `params` block.
@@ -350,20 +359,52 @@ Optional parameters can have a default value.
 ```ruby
 params do
   optional :color, type: String, default: 'blue'
+  optional :random_number, type: Integer, default: -> { Random.rand(1..100) }
+  optional :non_random_number, type: Integer, default:  Random.rand(1..100)
 end
 ```
 
 Parameters can be restricted to a specific set of values with the `:values` option.
 
+Default values are eagerly evaluated. Above `:non_random_number` will evaluate to the same
+number for each call to the endpoint of this `params` block. To have the default evaluate
+at calltime use a lambda, like `:random_number` above.
+
 ```ruby
 params do
   requires :status, type: Symbol, values: [:not_started, :processing, :done]
 end
 ```
 
+The :values option can also be supplied with a `Proc` to be evalutated at runtime. For example, given a status
+model you may want to restrict by hashtags that you have previously defined in the `HashTag` model.
+
+```ruby
+params do
+  required :hashtag, type: String, values: -> { Hashtag.all.map(&:tag) }
+end
+```
+
 Parameters can be nested using `group` or by calling `requires` or `optional` with a block.
 In the above example, this means `params[:media][:url]` is required along with `params[:id]`,
-and `params[:audio][:mp3]` is required only if `params[:audio]` is present.
+and `params[:audio][:format]` is required only if `params[:audio]` is present.
+With a block, `group`, `requires` and `optional` accept an additional option `type` which can
+be either `Array` or `Hash`, and defaults to `Array`. Depending on the value, the nested
+parameters will be treated either as values of a hash or as values of hashes in an array.
+
+```ruby
+params do
+  optional :preferences, type: Array do
+    requires :key
+    requires :value
+  end
+
+  requires :name, type: Hash do
+    requires :first_name
+    requires :last_name
+  end
+end
+```
 
 ### Namespace Validation and Coercion
 
@@ -389,6 +430,23 @@ end
 The `namespace` method has a number of aliases, including: `group`, `resource`,
 `resources`, and `segment`. Use whichever reads the best for your API.
 
+You can conveniently define a route parameter as a namespace using `route_param`.
+
+```ruby
+namespace :statuses do
+  route_param :id do
+    desc "Returns all replies for a status."
+    get 'replies' do
+      Status.find(params[:id]).replies
+    end
+    desc "Returns a status."
+    get do
+      Status.find(params[:id])
+    end
+  end
+end
+```
+
 ### Custom Validators
 
 ```ruby
@@ -434,9 +492,9 @@ You can rescue a `Grape::Exceptions::ValidationErrors` and respond with a custom
 ```ruby
 rescue_from Grape::Exceptions::ValidationErrors do |e|
     Rack::Response.new({
-        'status' => e.status,
-        'message' => e.message,
-        'errors' => e.errors
+      status: e.status,
+      message: e.message,
+      errors: e.errors
     }.to_json, e.status)
 end
 ```
@@ -448,7 +506,6 @@ The validation errors are grouped by parameter name and can be accessed via ``Gr
 Grape supports I18n for parameter-related error messages, but will fallback to English if
 translations for the default locale have not been provided. See [en.yml](lib/grape/locale/en.yml) for message keys.
 
-
 ## Headers
 
 Request headers are available through the `headers` helper or from `env` in their original form.
@@ -468,7 +525,13 @@ end
 You can set a response header with `header` inside an API.
 
 ```ruby
-header "X-Robots-Tag", "noindex"
+header 'X-Robots-Tag', 'noindex'
+```
+
+When raising `error!`, pass additional headers as arguments.
+
+```ruby
+error! 'Unauthorized', 401, 'X-Error-Detail' => 'Invalid token.'
 ```
 
 ## Routes
@@ -520,13 +583,75 @@ class API < Grape::API
 end
 ```
 
+You can define reusable `params` using `helpers`.
+
+```ruby
+class API < Grape::API
+  helpers do
+    params :pagination do
+      optional :page, type: Integer
+      optional :per_page, type: Integer
+    end
+  end
+
+  desc "Get collection"
+  params do
+    use :pagination # aliases: includes, use_scope
+  end
+  get do
+    Collection.page(params[:page]).per(params[:per_page])
+  end
+end
+```
+
+You can also define reusable `params` using shared helpers.
+
+```ruby
+module SharedParams
+  extend Grape::API::Helpers
+
+  params :period do
+    optional :start_date
+    optional :end_date
+  end
+
+  params :pagination do
+    optional :page, type: Integer
+    optional :per_page, type: Integer
+  end
+end
+
+class API < Grape::API
+  helpers SharedParams
+
+  desc "Get collection"
+  params do
+    use :period, :pagination
+  end
+  get do
+    Collection.from(params[:start_date]).to(params[:end_date])
+              .page(params[:page]).per(params[:per_page])
+  end
+end
+```
+
+## Parameter Documentation
+
+You can attach additional documentation to `params` using a `documentation` hash.
+
+```ruby
+params do
+  optional :first_name, type: String, documentation: { example: 'Jim' }
+  requires :last_name, type: String, documentation: { example: 'Smith' }
+end
+```
+
 ## Cookies
 
 You can set, get and delete your cookies very simply using `cookies` method.
 
 ```ruby
 class API < Grape::API
-
   get 'status_count' do
     cookies[:status_count] ||= 0
     cookies[:status_count] += 1
@@ -536,7 +661,6 @@ class API < Grape::API
   delete 'status_count' do
     { status_count: cookies.delete(:status_count) }
   end
-
 end
 ```
 
@@ -544,10 +668,10 @@ Use a hash-based syntax to set more than one value.
 
 ```ruby
 cookies[:status_count] = {
-    value: 0,
-    expires: Time.tomorrow,
-    domain: '.twitter.com',
-    path: '/'
+  value: 0,
+  expires: Time.tomorrow,
+  domain: '.twitter.com',
+  path: '/'
 }
 
 cookies[:status_count][:value] +=1
@@ -570,11 +694,11 @@ cookies.delete :status_count, path: '/'
 You can redirect to a new url temporarily (302) or permanently (301).
 
 ```ruby
-redirect "/statuses"
+redirect '/statuses'
 ```
 
 ```ruby
-redirect "/statuses", permanent: true
+redirect '/statuses', permanent: true
 ```
 
 ## Allowed Methods
@@ -585,13 +709,11 @@ behavior with `do_not_route_head!`.
 
 ``` ruby
 class API < Grape::API
-
   do_not_route_head!
 
   get '/example' do
     # only responds to GET
   end
-
 end
 ```
 
@@ -601,7 +723,6 @@ include an "Allow" header listing the supported methods.
 
 ```ruby
 class API < Grape::API
-
   get '/rt_count' do
     { rt_count: current_user.rt_count }
   end
@@ -613,7 +734,6 @@ class API < Grape::API
     current_user.rt_count += params[:value].to_i
     { rt_count: current_user.rt_count }
   end
-
 end
 ```
 
@@ -646,14 +766,27 @@ curl -X DELETE -v http://localhost:3000/rt_count/
 You can abort the execution of an API method by raising errors with `error!`.
 
 ```ruby
-error! "Access Denied", 401
+error! 'Access Denied', 401
 ```
 
 You can also return JSON formatted objects by raising error! and passing a hash
 instead of a message.
 
 ```ruby
-error!({ "error" => "unexpected error", "detail" => "missing widget" }, 500)
+error!({ error: "unexpected error", detail: "missing widget" }, 500)
+```
+
+### Default Error HTTP Status Code
+
+By default Grape returns a 500 status code from `error!`. You can change this with `default_error_status`.
+
+``` ruby
+class API < Grape::API
+  default_error_status 400
+  get '/example' do
+    error! "This should have http status code 400"
+  end
+end
 ```
 
 ### Handling 404
@@ -684,10 +817,12 @@ You can also rescue specific exceptions.
 
 ```ruby
 class Twitter::API < Grape::API
-  rescue_from ArgumentError, NotImplementedError
+  rescue_from ArgumentError, UserDefinedError
 end
 ```
 
+In this case ```UserDefinedError``` must be inherited from ```StandardError```.
+
 The error format will match the request format. See "Content-Types" below.
 
 Custom error formatters for existing and additional types can be defined with a proc.
@@ -741,14 +876,49 @@ Or rescue specific exceptions.
 ```ruby
 class Twitter::API < Grape::API
   rescue_from ArgumentError do |e|
-    Rack::Response.new([ "ArgumentError: #{e.message}" ], 500)
+    Rack::Response.new([ "ArgumentError: #{e.message}" ], 500).finish
   end
   rescue_from NotImplementedError do |e|
-    Rack::Response.new([ "NotImplementedError: #{e.message}" ], 500)
+    Rack::Response.new([ "NotImplementedError: #{e.message}" ], 500).finish
   end
 end
 ```
 
+By default, `rescue_from` will rescue the exceptions listed and all their subclasses.
+
+Assume you have the following exception classes defined.
+
+```ruby
+module APIErrors
+  class ParentError < StandardError; end
+  class ChildError < ParentError; end
+end
+```
+
+Then the following `rescue_from` clause will rescue exceptions of type `APIErrors::ParentError` and its subclasses (in this case `APIErrors::ChildError`).
+
+```ruby
+rescue_from APIErrors::ParentError do |e|
+    Rack::Response.new({
+      error: "#{e.class} error",
+      message: e.message
+      }.to_json, e.status).finish
+end
+```
+
+To only rescue the base exception class, set `rescue_subclasses: false`.
+The code below will rescue exceptions of type `RuntimeError` but _not_ its subclasses.
+
+```ruby
+rescue_from RuntimeError, rescue_subclasses: false do |e|
+    Rack::Response.new(
+      status: e.status,
+      message: e.message,
+      errors: e.errors
+      }.to_json, e.status).finish
+end
+```
+
 #### Rails 3.x
 
 When mounted inside containers, such as Rails 3.x, errors like "404 Not Found" or
@@ -1008,7 +1178,6 @@ The following example exposes statuses.
 
 ```ruby
 module API
-
   module Entities
     class Status < Grape::Entity
       expose :user_name
@@ -1024,7 +1193,7 @@ module API
     version 'v1'
 
     desc 'Statuses index', {
-      object_fields: API::Entities::Status.documentation
+      params: API::Entities::Status.documentation
     }
     get '/statuses' do
       statuses = Status.all
@@ -1035,6 +1204,23 @@ module API
 end
 ```
 
+You can use entity documentation directly in the params block with `using: Entity.documentation`.
+
+```ruby
+module API
+  class Statuses < Grape::API
+    version 'v1'
+
+    desc 'Create a status', {
+      requires :all, except: [:ip], using: API::Entities::Status.documentation.except(:id)
+    }
+    post '/status' do
+      Status.create! params
+    end
+  end
+end
+```
+
 You can present with multiple entities using an optional Symbol argument.
 
 ```ruby
@@ -1062,7 +1248,7 @@ classes underneath the model they represent.
 ```ruby
 class Status
   def entity
-    Status.new(self)
+    Entity.new(self)
   end
 
   class Entity < Grape::Entity
@@ -1083,14 +1269,19 @@ You can use any Hypermedia representer, including [Roar](https://github.com/apot
 Roar renders JSON and works with the built-in Grape JSON formatter. Add `Roar::Representer::JSON`
 into your models or call `to_json` explicitly in your API implementation.
 
-Other alternatives include `ActiveModel::Serializers` via [grape-active_model_serializers](https://github.com/jrhe/grape-active_model_serializers).
-
 ### 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
 formatter.
 
+### Active Model Serializers
+
+You can use [Active Model Serializers](https://github.com/rails-api/active_model_serializers) serializers with the help of the
+[grape-active_model_serializers](https://github.com/jrhe/grape-active_model_serializers) gem, which defines a custom Grape AMS
+formatter.
+
+
 ## Authentication
 
 ### Basic and Digest Auth
@@ -1165,7 +1356,21 @@ end
 
 ## Before and After
 
-Execute a block before or after every API call with `before` and `after`.
+Blocks can be executed before or after every API call, using `before`, `after`,
+`before_validation` and `after_validation`.
+
+Before and after callbacks execute in the following order:
+
+1. `before`
+2. `before_validation`
+3. _validations_
+4. `after_validation`
+5. _the API call_
+6. `after`
+
+Steps 4, 5 and 6 only happen if validation succeeds.
+
+E.g. using `before`:
 
 ```ruby
 before do
@@ -1173,6 +1378,68 @@ before do
 end
 ```
 
+The block applies to every API call within and below the current namespace:
+
+```ruby
+class MyAPI < Grape::API
+  get '/' do
+    "root - #{@blah}"
+  end
+
+  namespace :foo do
+    before do
+      @blah = 'blah'
+    end
+
+    get '/' do
+      "root - foo - #{@blah}"
+    end
+
+    namespace :bar do
+      get '/' do
+        "root - foo - bar - #{@blah}"
+      end
+    end
+  end
+end
+```
+
+The behaviour is then:
+
+```bash
+GET /           # 'root - '
+GET /foo        # 'root - foo - blah'
+GET /foo/bar    # 'root - foo - bar - blah'
+```
+
+Params on a `namespace` (or whatever alias you are using) also work when using
+`before_validation` or `after_validation`:
+
+```ruby
+class MyAPI < Grape::API
+  params do
+    requires :blah, type: Integer
+  end
+  resource ':blah' do
+    after_validation do
+      # if we reach this point validations will have passed
+      @blah = declared(params, include_missing: false)[:blah]
+    end
+
+    get '/' do
+      @blah.class
+    end
+  end
+end
+```
+
+The behaviour is then:
+
+```bash
+GET /123        # 'Fixnum'
+GET /foo        # 400 error - 'blah is invalid'
+```
+
 ## Anchoring
 
 Grape by default anchors all request paths, which means that the request URL
@@ -1281,31 +1548,28 @@ Add API paths to `config/application.rb`.
 
 ```ruby
 # Auto-load API and its subdirectories
-config.paths.add "app/api", glob: "**/*.rb"
-config.autoload_paths += Dir["#{Rails.root}/app/api/*"]
+config.paths.add File.join("app", "api"), glob: File.join("**", "*.rb")
+config.autoload_paths += Dir[Rails.root.join("app", "api", "*")]
 ```
 
 Create `config/initializers/reload_api.rb`.
 
 ```ruby
 if Rails.env.development?
-
   ActiveSupport::Dependencies.explicitly_unloadable_constants << "Twitter::API"
 
-  api_files = Dir["#{Rails.root}/app/api/**/*.rb"]
+  api_files = Dir[Rails.root.join('app', 'api', '**', '*.rb')]
   api_reloader = ActiveSupport::FileUpdateChecker.new(api_files) do
     Rails.application.reload_routes!
   end
   ActionDispatch::Callbacks.to_prepare do
     api_reloader.execute_if_updated
   end
-
 end
 ```
 
 See [StackOverflow #3282655](http://stackoverflow.com/questions/3282655/ruby-on-rails-3-reload-lib-directory-for-each-request/4368838#4368838) for more information.
 
-
 ## Performance Monitoring
 
 Grape integrates with NewRelic via the
@@ -1314,14 +1578,10 @@ with Librato Metrics with the [grape-librato](https://github.com/seanmoon/grape-
 
 ## Contributing to Grape
 
-Grape is work of dozens of contributors. You're encouraged to submit pull requests, propose
+Grape is work of hundreds of contributors. You're encouraged to submit pull requests, propose
 features and discuss issues.
 
-* Fork the project
-* Write tests for your new feature or a test that reproduces a bug
-* Implement your feature or make a bug fix
-* Add a line to `CHANGELOG.md` describing your change
-* Commit, push and make a pull request. Bonus points for topic branches.
+See [CONTRIBUTING](CONTRIBUTING.md).
 
 ## License