grape 0.16.2 → 0.17.0

data/README.md

@@ -95,7 +95,7 @@
 
 ## What is Grape?
 
-Grape is a REST-like API micro-framework for Ruby. It's designed to run on Rack
+Grape is a REST-like API framework for Ruby. It's designed to run on Rack
 or complement existing web application frameworks such as Rails and Sinatra by
 providing a simple DSL to easily develop RESTful APIs. It has built-in support
 for common conventions, including multiple formats, subdomain/prefix restriction,
@@ -103,13 +103,14 @@ content negotiation, versioning and much more.
 
 ## Stable Release
 
-You're reading the documentation for the stable release of Grape, 0.16.2.
+You're reading the documentation for the stable release of Grape.
 Please read [UPGRADING](UPGRADING.md) when upgrading from a previous version.
 
 ## Project Resources
 
 * [Grape Website](http://www.ruby-grape.org)
-* Need help? [Grape Google Group](http://groups.google.com/group/ruby-grape)
+* 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
 
@@ -370,7 +371,8 @@ Using this versioning strategy, clients should pass the desired version in the H
 By default, the first matching version is used when no `Accept-Version` header is
 supplied. This behavior is similar to routing in Rails. To circumvent this default behavior,
 one could use the `:strict` option. When this option is set to `true`, a `406 Not Acceptable` error
-is returned when no correct `Accept` header is supplied.
+is returned when no correct `Accept` header is supplied and the `:cascade` option is set to `false`.
+Otherwise a `404 Not Found` error is returned by Rack if no other route matches.
 
 ### Param
 
@@ -552,6 +554,52 @@ The returned hash is a `Hashie::Mash` instance, allowing you to access parameter
 The `#declared` method is not available to `before` filters, as those are evaluated prior
 to parameter coercion.
 
+### Include parent namespaces
+
+By default `declared(params)` includes parameters that were defined in all parent namespaces. If you want to return only parameters from your current namespace, you can set `include_parent_namespaces` option to `false`.
+
+````ruby
+format :json
+
+namespace :parent do
+  params do
+    requires :parent_name, type: String
+  end
+
+  namespace ':parent_name' do
+    params do
+      requires :child_name, type: String
+    end
+    get ':child_name' do
+      {
+        'without_parent_namespaces' => declared(params, include_parent_namespaces: false),
+        'with_parent_namespaces' => declared(params, include_parent_namespaces: true),
+      }
+    end
+  end
+end
+````
+
+**Request**
+
+````bash
+curl -X GET -H "Content-Type: application/json" localhost:9292/parent/foo/bar
+````
+
+**Response**
+
+````json
+{
+  "without_parent_namespaces": {
+    "child_name": "bar"
+  },
+  "with_parent_namespaces": {
+    "parent_name": "foo",
+    "child_name": "bar"
+  },
+}
+````
+
 ### Include missing
 
 By default `declared(params)` includes parameters that have `nil` values. If you want to return only the parameters that are not `nil`, you can use the `include_missing` option. By default, `include_missing` is set to `true`. Consider the following API:
@@ -938,6 +986,19 @@ params do
 end
 ```
 
+In the example above Grape will use `blank?` to check whether the `shelf_id` param is present.
+
+Given also takes a `Proc` with custom code. Below, the param `description` is required only if the value of `category` is equal `foo`:
+
+```ruby
+params do
+  optional :category
+  given category: ->(val) { val == 'foo' } do
+    requires :description
+  end
+end
+```
+
 ### Built-in Validators
 
 #### `allow_blank`
@@ -1804,6 +1865,17 @@ class Twitter::API < Grape::API
 end
 ```
 
+Grape can also rescue from all exceptions and still use the built-in exception handing.
+This will give the same behavior as `rescue_from :all` with the addition that Grape will use the exception handling defined by all Exception classes that inherit Grape::Exceptions::Base.
+
+The intent of this setting is to provide a simple way to cover the most common exceptions and return any unexpected exceptions in the API format.
+
+```ruby
+class Twitter::API < Grape::API
+  rescue_from :grape_exceptions
+end
+```
+
 You can also rescue specific exceptions.
 
 ```ruby
@@ -1814,6 +1886,18 @@ end
 
 In this case ```UserDefinedError``` must be inherited from ```StandardError```.
 
+Notice that you could combine these two approaches (rescuing custom errors takes precedence). For example, it's useful for handling all exceptions except Grape validation errors.
+
+```ruby
+class Twitter::API < Grape::API
+  rescue_from Grape::Exceptions::ValidationErrors do |e|
+    error!(e, 400)
+  end
+
+  rescue_from :all
+end
+```
+
 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.
@@ -1861,7 +1945,7 @@ class Twitter::API < Grape::API
 end
 ```
 
-You can also rescue specific exceptions with a code block and handle the Rack response at the lowest level.
+You can also rescue all exceptions with a code block and handle the Rack response at the lowest level.
 
 ```ruby
 class Twitter::API < Grape::API
@@ -1955,6 +2039,30 @@ class Twitter::API < Grape::API
 end
 ```
 
+#### Rescuing exceptions inside namespaces
+
+You could put `rescue_from` clauses inside a namespace and they will take precedence over ones
+defined in the root scope:
+
+```ruby
+class Twitter::API < Grape::API
+  rescue_from ArgumentError do |e|
+    error!("outer")
+  end
+
+  namespace :statuses do
+    rescue_from ArgumentError do |e|
+      error!("inner")
+    end
+    get do
+      raise ArgumentError.new
+    end
+  end
+end
+```
+
+Here `'inner'` will be result of handling occured `ArgumentError`.
+
 #### Unrescuable Exceptions
 
 `Grape::Exceptions::InvalidVersionHeader`, which is raised when the version in the request header doesn't match the currently evaluated version for the endpoint, will _never_ be rescued from a `rescue_from` block (even a `rescue_from :all`) This is because Grape relies on Rack to catch that error and try the next versioned-route for cases where there exist identical Grape endpoints with different versions.
@@ -2314,7 +2422,7 @@ module API
       expose :text, documentation: { type: 'string', desc: 'Status update text.' }
       expose :ip, if: { type: :full }
       expose :user_type, :user_id, if: ->(status, options) { status.user.public? }
-      expose :digest do |status, options| 
+      expose :digest do |status, options|
         Digest::MD5.hexdigest(status.txt)
       end
       expose :replies, using: API::Status, as: :replies
@@ -2805,7 +2913,27 @@ Your middleware can overwrite application response as follows, except error case
 ```ruby
 class Overwriter < Grape::Middleware::Base
   def after
-    [200, { 'Content-Type' => 'text/plain' }, ['Overwrited.']]
+    [200, { 'Content-Type' => 'text/plain' }, ['Overwritten.']]
+  end
+end
+```
+
+You can add your custom middleware with `use`, that push the middleware onto the stack, and you can also control where the middleware is inserted using `insert`, `insert_before` and `insert_after`.
+
+```ruby
+class CustomOverwriter < Grape::Middleware::Base
+  def after
+    [200, { 'Content-Type' => 'text/plain' }, [@options[:message]]]
+  end
+end
+
+
+class API < Grape::API
+  use Overwriter
+  insert_before Overwriter, CustomOverwriter, message: 'Overwritten again.'
+  insert 0, CustomOverwriter, message: 'Overwrites all other middleware.'
+
+  get '/' do
   end
 end
 ```

data/Rakefile

@@ -23,43 +23,47 @@ RuboCop::RakeTask.new
 
 task default: [:rubocop, :spec]
 
-require 'yard'
-DOC_FILES = ['lib/**/*.rb', 'README.md']
+begin
+  require 'yard'
+  DOC_FILES = ['lib/**/*.rb', 'README.md'].freeze
 
-YARD::Rake::YardocTask.new(:doc) do |t|
-  t.files = DOC_FILES
-end
-
-namespace :doc do
-  YARD::Rake::YardocTask.new(:pages) do |t|
-    t.files   = DOC_FILES
-    t.options = ['-o', '../grape.doc/docs']
+  YARD::Rake::YardocTask.new(:doc) do |t|
+    t.files = DOC_FILES
   end
 
-  namespace :pages do
-    desc 'Check out gh-pages.'
-    task :checkout do
-      dir = File.dirname(__FILE__) + '/../grape.doc'
-      unless Dir.exist?(dir)
-        Dir.mkdir(dir)
-        Dir.chdir(dir) do
-          system('git init')
-          system('git remote add origin git@github.com:ruby-grape/grape.git')
-          system('git pull')
-          system('git checkout gh-pages')
+  namespace :doc do
+    YARD::Rake::YardocTask.new(:pages) do |t|
+      t.files   = DOC_FILES
+      t.options = ['-o', '../grape.doc/docs']
+    end
+
+    namespace :pages do
+      desc 'Check out gh-pages.'
+      task :checkout do
+        dir = File.dirname(__FILE__) + '/../grape.doc'
+        unless Dir.exist?(dir)
+          Dir.mkdir(dir)
+          Dir.chdir(dir) do
+            system('git init')
+            system('git remote add origin git@github.com:ruby-grape/grape.git')
+            system('git pull')
+            system('git checkout gh-pages')
+          end
         end
       end
-    end
 
-    desc 'Generate and publish YARD docs to GitHub pages.'
-    task publish: ['doc:pages:checkout', 'doc:pages'] do
-      Dir.chdir(File.dirname(__FILE__) + '/../grape.doc') do
-        system('git checkout gh-pages')
-        system('git add .')
-        system('git add -u')
-        system("git commit -m 'Generating docs for version #{Grape::VERSION}.'")
-        system('git push origin gh-pages')
+      desc 'Generate and publish YARD docs to GitHub pages.'
+      task publish: ['doc:pages:checkout', 'doc:pages'] do
+        Dir.chdir(File.dirname(__FILE__) + '/../grape.doc') do
+          system('git checkout gh-pages')
+          system('git add .')
+          system('git add -u')
+          system("git commit -m 'Generating docs for version #{Grape::VERSION}.'")
+          system('git push origin gh-pages')
+        end
       end
     end
   end
+rescue LoadError # rubocop:disable Lint/HandleExceptions
+  # ignore
 end

data/UPGRADING.md

@@ -1,6 +1,27 @@
 Upgrading Grape
 ===============
 
+### Upgrading to >= 0.17.0
+
+#### Removed official support for Ruby < 2.2.2
+
+Grape is no longer automatically tested against versions of Ruby prior to 2.2.2. This is because of its dependency on activesupport which, with version 5.0.0, now requires at least Ruby 2.2.2.
+
+See [#1441](https://github.com/ruby-grape/grape/pull/1441) for nmore information.
+
+#### Changed priority of `rescue_from` clauses applying
+
+The `rescue_from` clauses declared inside a namespace would take a priority over ones declared in the root scope.
+This could possibly affect those users who use different `rescue_from` clauses in root scope and in namespaces.
+
+See [#1405](https://github.com/ruby-grape/grape/pull/1405) for more inforomation.
+
+#### Helper methods injected inside `rescue_from` in middleware
+
+Helper methods are injected inside `rescue_from` may cause undesirable effects. For example, definining a helper method called `error!` will take precendence over the built-in `error!` method and should be renamed.
+
+See [#1451](https://github.com/ruby-grape/grape/issues/1451) for an example.
+
 ### Upgrading to >= 0.16.0
 
 #### Replace rack-mount with new router

data/gemfiles/rack_1.5.2.gemfile

@@ -5,9 +5,30 @@ source 'https://rubygems.org'
 gem 'rack', '1.5.2'
 
 group :development, :test do
+  gem 'bundler'
+  gem 'rake'
+  gem 'rubocop', '0.39.0'
+end
+
+group :development do
   gem 'guard'
   gem 'guard-rspec'
   gem 'guard-rubocop'
+  gem 'yard'
+  gem 'appraisal'
+  gem 'benchmark-ips'
+  gem 'redcarpet'
+end
+
+group :test do
+  gem 'grape-entity', '0.5.0'
+  gem 'maruku'
+  gem 'rack-test'
+  gem 'rspec', '~> 3.0'
+  gem 'cookiejar'
+  gem 'rack-jsonp', require: 'rack/jsonp'
+  gem 'mime-types', '< 3.0'
+  gem 'danger', '~> 2.0'
 end
 
 gemspec path: '../'

data/gemfiles/rails_3.gemfile

@@ -2,13 +2,34 @@
 
 source 'https://rubygems.org'
 
-gem 'rails', '3.2.22'
+gem 'rails', '3.2.19'
 gem 'rack-cache', '<= 1.2'
 
 group :development, :test do
+  gem 'bundler'
+  gem 'rake'
+  gem 'rubocop', '0.39.0'
+end
+
+group :development do
   gem 'guard'
   gem 'guard-rspec'
   gem 'guard-rubocop'
+  gem 'yard'
+  gem 'appraisal'
+  gem 'benchmark-ips'
+  gem 'redcarpet'
+end
+
+group :test do
+  gem 'grape-entity', '0.5.0'
+  gem 'maruku'
+  gem 'rack-test'
+  gem 'rspec', '~> 3.0'
+  gem 'cookiejar'
+  gem 'rack-jsonp', require: 'rack/jsonp'
+  gem 'mime-types', '< 3.0'
+  gem 'danger', '~> 2.0'
 end
 
 gemspec path: '../'

data/gemfiles/rails_4.gemfile

@@ -5,9 +5,30 @@ source 'https://rubygems.org'
 gem 'rails', '4.1.6'
 
 group :development, :test do
+  gem 'bundler'
+  gem 'rake'
+  gem 'rubocop', '0.39.0'
+end
+
+group :development do
   gem 'guard'
   gem 'guard-rspec'
   gem 'guard-rubocop'
+  gem 'yard'
+  gem 'appraisal'
+  gem 'benchmark-ips'
+  gem 'redcarpet'
+end
+
+group :test do
+  gem 'grape-entity', '0.5.0'
+  gem 'maruku'
+  gem 'rack-test'
+  gem 'rspec', '~> 3.0'
+  gem 'cookiejar'
+  gem 'rack-jsonp', require: 'rack/jsonp'
+  gem 'mime-types', '< 3.0'
+  gem 'danger', '~> 2.0'
 end
 
 gemspec path: '../'

data/gemfiles/rails_5.gemfile

@@ -0,0 +1,34 @@
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'rails', '5.0.0'
+
+group :development, :test do
+  gem 'bundler'
+  gem 'rake'
+  gem 'rubocop', '0.39.0'
+end
+
+group :development do
+  gem 'guard'
+  gem 'guard-rspec'
+  gem 'guard-rubocop'
+  gem 'yard'
+  gem 'appraisal'
+  gem 'benchmark-ips'
+  gem 'redcarpet'
+end
+
+group :test do
+  gem 'grape-entity', '0.5.0'
+  gem 'maruku'
+  gem 'rack-test'
+  gem 'rspec', '~> 3.0'
+  gem 'cookiejar'
+  gem 'rack-jsonp', require: 'rack/jsonp'
+  gem 'mime-types', '< 3.0'
+  gem 'danger', '~> 2.0'
+end
+
+gemspec path: '../'