grape-security 0.8.0

data/RELEASING.md

@@ -0,0 +1,105 @@
+Releasing Grape
+===============
+
+There're no particular rules about when to release Grape. Release bug fixes frequenty, features not so frequently and breaking API changes rarely.
+
+### Release
+
+Run tests, check that all tests succeed locally.
+
+```
+bundle install
+rake
+```
+
+Check that the last build succeeded in [Travis CI](https://travis-ci.org/intridea/grape) for all supported platforms.
+
+Those with r/w permissions to the [master Intridea repository](https://github.com/intridea/grape) generally have large Grape-based projects. Point one to Grape HEAD and run all your API tests to catch any obvious regressions.
+
+```
+gem grape, github: 'intridea/grape'
+```
+
+Increment the version, modify [lib/grape/version.rb](lib/grape/version.rb).
+
+*  Increment the third number if the release has bug fixes and/or very minor features, only (eg. change `0.5.1` to `0.5.2`).
+*  Increment the second number if the release contains major features or breaking API changes (eg. change `0.5.1` to `0.6.0`).
+
+Modify the "Stable Release" section in [README.md](README.md). Change the text to reflect that this is going to be the documentation for a stable release. Remove references to the previous release of Grape. Keep the file open, you'll have to undo this change after the release.
+
+```
+## Stable Release
+
+You're reading the documentation for the stable release of Grape, 0.6.0.
+```
+
+Change "Next Release" in [CHANGELOG.md](CHANGELOG.md) to the new version.
+
+```
+0.6.0 (9/16/2013)
+=================
+```
+
+Remove the line with "Your contribution here.", since there will be no more contributions to this release.
+
+Commit your changes.
+
+```
+git add README.md CHANGELOG.md lib/grape/version.rb
+git commit -m "Preparing for release, 0.6.0."
+git push origin master
+```
+
+Release.
+
+```
+$ rake release
+
+grape 0.6.0 built to pkg/grape-0.6.0.gem.
+Tagged v0.6.0.
+Pushed git commits and tags.
+Pushed grape 0.6.0 to rubygems.org.
+```
+
+### Prepare for the Next Version
+
+Modify the "Stable Release" section in [README.md](README.md). Change the text to reflect that this is going to be the next release.
+
+```
+## Stable Release
+
+You're reading the documentation for the next release of Grape, which should be 0.6.1.
+The current stable release is [0.6.0](https://github.com/intridea/grape/blob/v0.6.0/README.md).
+```
+
+Add the next release to [CHANGELOG.md](CHANGELOG.md).
+
+```
+Next Release
+============
+
+* Your contribution here.
+```
+
+Comit your changes.
+
+```
+git add CHANGELOG.md README.md
+git commit -m "Preparing for next release."
+git push origin master
+```
+
+### Make an Announcement
+
+Make an announcement on the [ruby-grape@googlegroups.com](mailto:ruby-grape@googlegroups.com) mailing list. The general format is as follows.
+
+```
+Grape 0.6.0 has been released.
+
+There were 8 contributors to this release, not counting documentation.
+
+Please note the breaking API change in ...
+
+[copy/paste CHANGELOG here]
+
+```

data/Rakefile

@@ -0,0 +1,69 @@
+require 'rubygems'
+require 'bundler'
+Bundler.setup :default, :test, :development
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec
+
+require 'rainbow/ext/string' unless String.respond_to?(:color)
+require 'rubocop/rake_task'
+Rubocop::RakeTask.new(:rubocop)
+
+task default: [:rubocop, :spec]
+
+begin
+  require 'yard'
+  DOC_FILES = ['lib/**/*.rb', 'README.md']
+
+  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']
+    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:intridea/grape.git")
+            system("git pull")
+            system("git checkout gh-pages")
+          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")
+        end
+      end
+    end
+  end
+rescue LoadError
+  puts "You need to install YARD."
+end

data/UPGRADING.md

@@ -0,0 +1,124 @@
+Upgrading Grape
+===============
+
+### Upgrading to >= 0.7.0
+
+#### Changes in Exception Handling
+
+Assume you have the following exception classes defined.
+
+```ruby
+class ParentError < StandardError; end
+class ChildError < ParentError; end
+```
+
+In Grape <= 0.6.1, the `rescue_from` keyword only handled the exact exception being raised. The following code would rescue `ParentError`, but not `ChildError`.
+
+```ruby
+rescue_from ParentError do |e|
+  # only rescue ParentError
+end
+```
+
+This made it impossible to rescue an exception hieararchy, which is a more sensible default. In Grape 0.7.0 or newer, both `ParentError` and `ChildError` are rescued.
+
+```ruby
+rescue_from ParentError do |e|
+  # rescue both ParentError and ChildError
+end
+```
+
+To only rescue the base exception class, set `rescue_subclasses: false`.
+
+```ruby
+rescue_from ParentError, rescue_subclasses: false do |e|
+  # only rescue ParentError
+end
+```
+
+See [#544](https://github.com/intridea/grape/pull/544) for more information.
+
+
+#### Changes in the Default HTTP Status Code
+
+In Grape <= 0.6.1, the default status code returned from `error!` was 403.
+
+```ruby
+error! "You may not reticulate this spline!" # yields HTTP error 403
+```
+
+This was a bad default value, since 403 means "Forbidden". Change any call to `error!` that does not specify a status code to specify one. The new default value is a more sensible default of 500, which is "Internal Server Error".
+
+```ruby
+error! "You may not reticulate this spline!", 403 # yields HTTP error 403
+```
+
+You may also use `default_error_status` to change the global default.
+
+```ruby
+default_error_status 400
+```
+
+See [#525](https://github.com/intridea/Grape/pull/525) for more information.
+
+
+#### Changes in Parameter Declaration and Validation
+
+In Grape <= 0.6.1, `group`, `optional` and `requires` keywords with a block accepted either an `Array` or a `Hash`.
+
+```ruby
+params do
+  requires :id, type: Integer
+  group :name do
+    requires :first_name
+    requires :last_name
+  end
+end
+```
+
+This caused the ambiguity and unexpected errors described in [#543](https://github.com/intridea/Grape/issues/543).
+
+In Grape 0.7.0, the `group`, `optional` and `requires` keywords take an additional `type` attribute which defaults to `Array`. This means that without a `type` attribute, these nested parameters will no longer accept a single hash, only an array (of hashes).
+
+Whereas in 0.6.1 the API above accepted the following json, it no longer does in 0.7.0.
+
+```json
+{
+  "id": 1,
+  "name": {
+    "first_name": "John",
+    "last_name" : "Doe"
+  }
+}
+```
+
+The `params` block should now read as follows.
+
+```ruby
+params do
+  requires :id, type: Integer
+  requires :name, type: Hash do
+    requires :first_name
+    requires :last_name
+  end
+end
+```
+
+See [#545](https://github.com/intridea/Grape/pull/545) for more information.
+
+
+### Upgrading to 0.6.0
+
+In Grape <= 0.5.0, only the first validation error was raised and processing aborted. Validation errors are now collected and a single `Grape::Exceptions::ValidationErrors` exception is raised. You can access the collection of validation errors as `.errors`.
+
+```ruby
+rescue_from Grape::Exceptions::Validations do |e|
+  Rack::Response.new({
+    status: 422,
+    message: e.message,
+    errors: e.errors
+  }.to_json, 422)
+end
+```
+
+For more information see [#462](https://github.com/intridea/grape/issues/462).

data/grape-security.gemspec

@@ -0,0 +1,39 @@
+$:.push File.expand_path("../lib", __FILE__)
+require "grape/version"
+
+Gem::Specification.new do |s|
+  s.name        = "grape-security"
+  s.version     = Grape::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Michael Bleigh"]
+  s.email       = ["michael@intridea.com"]
+  s.homepage    = "https://github.com/intridea/grape"
+  s.summary     = %q{Backported security patched version] A simple Ruby framework for building REST-like APIs.}
+  s.description = %q{[Backported security patched version] A Ruby framework for rapid API development with great conventions.}
+  s.license     = "MIT"
+
+  s.rubyforge_project = "grape"
+
+  s.add_runtime_dependency 'rack', '>= 1.3.0'
+  s.add_runtime_dependency 'rack-mount'
+  s.add_runtime_dependency 'rack-accept'
+  s.add_runtime_dependency 'activesupport'
+  s.add_runtime_dependency 'multi_json', '>= 1.3.2'
+  s.add_runtime_dependency 'multi_xml', '>= 0.5.2'
+  s.add_runtime_dependency 'hashie', '>= 2.1.0'
+  s.add_runtime_dependency 'virtus', '>= 1.0.0'
+  s.add_runtime_dependency 'builder'
+
+  s.add_development_dependency 'grape-entity', '>= 0.2.0'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'maruku'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'rack-test'
+  s.add_development_dependency 'rspec', '~> 2.9'
+  s.add_development_dependency 'bundler'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/grape.rb

@@ -0,0 +1,99 @@
+require 'logger'
+require 'rack'
+require 'rack/mount'
+require 'rack/builder'
+require 'rack/accept'
+require 'rack/auth/basic'
+require 'rack/auth/digest/md5'
+require 'hashie'
+require 'set'
+require 'active_support/core_ext/hash/indifferent_access'
+require 'active_support/ordered_hash'
+require 'active_support/core_ext/object/conversions'
+require 'active_support/core_ext/array/extract_options'
+require 'grape/util/deep_merge'
+require 'grape/util/content_types'
+require 'multi_json'
+require 'multi_xml'
+require 'virtus'
+require 'i18n'
+require 'thread'
+
+I18n.load_path << File.expand_path('../grape/locale/en.yml', __FILE__)
+
+module Grape
+  autoload :API,                 'grape/api'
+  autoload :Endpoint,            'grape/endpoint'
+
+  autoload :Route,               'grape/route'
+  autoload :Namespace,           'grape/namespace'
+
+  autoload :Path,                'grape/path'
+
+  autoload :Cookies,             'grape/cookies'
+  autoload :Validations,         'grape/validations'
+  autoload :Request,             'grape/http/request'
+
+  module Exceptions
+    autoload :Base,                           'grape/exceptions/base'
+    autoload :Validation,                     'grape/exceptions/validation'
+    autoload :ValidationErrors,               'grape/exceptions/validation_errors'
+    autoload :MissingVendorOption,            'grape/exceptions/missing_vendor_option'
+    autoload :MissingMimeType,                'grape/exceptions/missing_mime_type'
+    autoload :MissingOption,                  'grape/exceptions/missing_option'
+    autoload :InvalidFormatter,               'grape/exceptions/invalid_formatter'
+    autoload :InvalidVersionerOption,         'grape/exceptions/invalid_versioner_option'
+    autoload :UnknownValidator,               'grape/exceptions/unknown_validator'
+    autoload :UnknownOptions,                 'grape/exceptions/unknown_options'
+    autoload :InvalidWithOptionForRepresent,  'grape/exceptions/invalid_with_option_for_represent'
+    autoload :IncompatibleOptionValues,       'grape/exceptions/incompatible_option_values'
+  end
+
+  module ErrorFormatter
+    autoload :Base,              'grape/error_formatter/base'
+    autoload :Json,              'grape/error_formatter/json'
+    autoload :Txt,               'grape/error_formatter/txt'
+    autoload :Xml,               'grape/error_formatter/xml'
+  end
+
+  module Formatter
+    autoload :Base,              'grape/formatter/base'
+    autoload :Json,              'grape/formatter/json'
+    autoload :SerializableHash,  'grape/formatter/serializable_hash'
+    autoload :Txt,               'grape/formatter/txt'
+    autoload :Xml,               'grape/formatter/xml'
+  end
+
+  module Parser
+    autoload :Base,              'grape/parser/base'
+    autoload :Json,              'grape/parser/json'
+    autoload :Xml,               'grape/parser/xml'
+  end
+
+  module Middleware
+    autoload :Base,              'grape/middleware/base'
+    autoload :Versioner,         'grape/middleware/versioner'
+    autoload :Formatter,         'grape/middleware/formatter'
+    autoload :Error,             'grape/middleware/error'
+
+    module Auth
+      autoload :OAuth2,         'grape/middleware/auth/oauth2'
+      autoload :Base,	          'grape/middleware/auth/base'
+      autoload :Basic,          'grape/middleware/auth/basic'
+      autoload :Digest,	        'grape/middleware/auth/digest'
+    end
+
+    module Versioner
+      autoload :Path,                 'grape/middleware/versioner/path'
+      autoload :Header,               'grape/middleware/versioner/header'
+      autoload :Param,                'grape/middleware/versioner/param'
+      autoload :AcceptVersionHeader,  'grape/middleware/versioner/accept_version_header'
+    end
+  end
+
+  module Util
+    autoload :HashStack,         'grape/util/hash_stack'
+  end
+end
+
+require 'grape/version'

data/lib/grape/api.rb

@@ -0,0 +1,646 @@
+module Grape
+  # The API class is the primary entry point for
+  # creating Grape APIs.Users should subclass this
+  # class in order to build an API.
+  class API
+    extend Validations::ClassMethods
+
+    class << self
+      attr_reader :endpoints, :instance, :routes, :route_set, :settings, :versions
+      attr_writer :logger
+
+      LOCK = Mutex.new
+
+      def logger(logger = nil)
+        if logger
+          @logger = logger
+        else
+          @logger ||= Logger.new($stdout)
+        end
+      end
+
+      def reset!
+        @settings  = Grape::Util::HashStack.new
+        @route_set = Rack::Mount::RouteSet.new
+        @endpoints = []
+        @routes = nil
+        reset_validations!
+      end
+
+      def compile
+        @instance ||= new
+      end
+
+      def change!
+        @instance = nil
+      end
+
+      def call(env)
+        LOCK.synchronize { compile } unless instance
+        call!(env)
+      end
+
+      def call!(env)
+        instance.call(env)
+      end
+
+      # Set a configuration value for this namespace.
+      #
+      # @param key [Symbol] The key of the configuration variable.
+      # @param value [Object] The value to which to set the configuration variable.
+      def set(key, value)
+        settings[key.to_sym] = value
+      end
+
+      # Add to a configuration value for this
+      # namespace.
+      #
+      # @param key [Symbol] The key of the configuration variable.
+      # @param value [Object] The value to which to set the configuration variable.
+      def imbue(key, value)
+        settings.imbue(key, value)
+      end
+
+      # Define a root URL prefix for your entire API.
+      def prefix(prefix = nil)
+        prefix ? set(:root_prefix, prefix) : settings[:root_prefix]
+      end
+
+      # Do not route HEAD requests to GET requests automatically
+      def do_not_route_head!
+        set(:do_not_route_head, true)
+      end
+
+      # Do not automatically route OPTIONS
+      def do_not_route_options!
+        set(:do_not_route_options, true)
+      end
+
+      # Specify an API version.
+      #
+      # @example API with legacy support.
+      #   class MyAPI < Grape::API
+      #     version 'v2'
+      #
+      #     get '/main' do
+      #       {some: 'data'}
+      #     end
+      #
+      #     version 'v1' do
+      #       get '/main' do
+      #         {legacy: 'data'}
+      #       end
+      #     end
+      #   end
+      #
+      def version(*args, &block)
+        if args.any?
+          options = args.pop if args.last.is_a? Hash
+          options ||= {}
+          options = { using: :path }.merge(options)
+
+          raise Grape::Exceptions::MissingVendorOption.new if options[:using] == :header && !options.key?(:vendor)
+
+          @versions = versions | args
+          nest(block) do
+            set(:version, args)
+            set(:version_options, options)
+          end
+        end
+
+        @versions.last unless @versions.nil?
+      end
+
+      # Add a description to the next namespace or function.
+      def desc(description, options = {})
+        @last_description = options.merge(description: description)
+      end
+
+      # Specify the default format for the API's serializers.
+      # May be `:json` or `:txt` (default).
+      def default_format(new_format = nil)
+        new_format ? set(:default_format, new_format.to_sym) : settings[:default_format]
+      end
+
+      # Specify the format for the API's serializers.
+      # May be `:json`, `:xml`, `:txt`, etc.
+      def format(new_format = nil)
+        if new_format
+          set(:format, new_format.to_sym)
+          # define the default error formatters
+          set(:default_error_formatter, Grape::ErrorFormatter::Base.formatter_for(new_format, {}))
+          # define a single mime type
+          mime_type = content_types[new_format.to_sym]
+          raise Grape::Exceptions::MissingMimeType.new(new_format) unless mime_type
+          settings.imbue(:content_types, new_format.to_sym => mime_type)
+        else
+          settings[:format]
+        end
+      end
+
+      # Specify a custom formatter for a content-type.
+      def formatter(content_type, new_formatter)
+        settings.imbue(:formatters, content_type.to_sym => new_formatter)
+      end
+
+      # Specify a custom parser for a content-type.
+      def parser(content_type, new_parser)
+        settings.imbue(:parsers, content_type.to_sym => new_parser)
+      end
+
+      # Specify a default error formatter.
+      def default_error_formatter(new_formatter_name = nil)
+        if new_formatter_name
+          new_formatter = Grape::ErrorFormatter::Base.formatter_for(new_formatter_name, {})
+          set(:default_error_formatter, new_formatter)
+        else
+          settings[:default_error_formatter]
+        end
+      end
+
+      def error_formatter(format, options)
+        if options.is_a?(Hash) && options.key?(:with)
+          formatter = options[:with]
+        else
+          formatter = options
+        end
+
+        settings.imbue(:error_formatters, format.to_sym => formatter)
+      end
+
+      # Specify additional content-types, e.g.:
+      #   content_type :xls, 'application/vnd.ms-excel'
+      def content_type(key, val)
+        settings.imbue(:content_types, key.to_sym => val)
+      end
+
+      # All available content types.
+      def content_types
+        Grape::ContentTypes.content_types_for(settings[:content_types])
+      end
+
+      # Specify the default status code for errors.
+      def default_error_status(new_status = nil)
+        new_status ? set(:default_error_status, new_status) : settings[:default_error_status]
+      end
+
+      # Allows you to rescue certain exceptions that occur to return
+      # a grape error rather than raising all the way to the
+      # server level.
+      #
+      # @example Rescue from custom exceptions
+      #     class ExampleAPI < Grape::API
+      #       class CustomError < StandardError; end
+      #
+      #       rescue_from CustomError
+      #     end
+      #
+      # @overload rescue_from(*exception_classes, options = {})
+      #   @param [Array] exception_classes A list of classes that you want to rescue, or
+      #     the symbol :all to rescue from all exceptions.
+      #   @param [Block] block Execution block to handle the given exception.
+      #   @param [Hash] options Options for the rescue usage.
+      #   @option options [Boolean] :backtrace Include a backtrace in the rescue response.
+      #   @option options [Boolean] :rescue_subclasses Also rescue subclasses of exception classes
+      #   @param [Proc] handler Execution proc to handle the given exception as an
+      #     alternative to passing a block
+      def rescue_from(*args, &block)
+        if args.last.is_a?(Proc)
+          handler = args.pop
+        elsif block_given?
+          handler = block
+        end
+
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        handler ||= proc { options[:with] } if options.key?(:with)
+
+        if args.include?(:all)
+          set(:rescue_all, true)
+          imbue :all_rescue_handler, handler
+        else
+          handler_type =
+            case options[:rescue_subclasses]
+            when nil, true
+              :rescue_handlers
+            else
+              :base_only_rescue_handlers
+            end
+
+          imbue handler_type, Hash[args.map { |arg| [arg, handler] }]
+        end
+
+        imbue(:rescue_options, options)
+      end
+
+      # Allows you to specify a default representation entity for a
+      # class. This allows you to map your models to their respective
+      # entities once and then simply call `present` with the model.
+      #
+      # @example
+      #   class ExampleAPI < Grape::API
+      #     represent User, with: Entity::User
+      #
+      #     get '/me' do
+      #       present current_user # with: Entity::User is assumed
+      #     end
+      #   end
+      #
+      # Note that Grape will automatically go up the class ancestry to
+      # try to find a representing entity, so if you, for example, define
+      # an entity to represent `Object` then all presented objects will
+      # bubble up and utilize the entity provided on that `represent` call.
+      #
+      # @param model_class [Class] The model class that will be represented.
+      # @option options [Class] :with The entity class that will represent the model.
+      def represent(model_class, options)
+        raise Grape::Exceptions::InvalidWithOptionForRepresent.new unless options[:with] && options[:with].is_a?(Class)
+        imbue(:representations, model_class => options[:with])
+      end
+
+      # Add helper methods that will be accessible from any
+      # endpoint within this namespace (and child namespaces).
+      #
+      # When called without a block, all known helpers within this scope
+      # are included.
+      #
+      # @param [Module] new_mod optional module of methods to include
+      # @param [Block] block optional block of methods to include
+      #
+      # @example Define some helpers.
+      #
+      #     class ExampleAPI < Grape::API
+      #       helpers do
+      #         def current_user
+      #           User.find_by_id(params[:token])
+      #         end
+      #       end
+      #     end
+      #
+      def helpers(new_mod = nil, &block)
+        if block_given? || new_mod
+          mod = settings.peek[:helpers] || Module.new
+          if new_mod
+            inject_api_helpers_to_mod(new_mod) if new_mod.is_a?(Helpers)
+            mod.class_eval do
+              include new_mod
+            end
+          end
+          if block_given?
+            inject_api_helpers_to_mod(mod) do
+              mod.class_eval(&block)
+            end
+          end
+          set(:helpers, mod)
+        else
+          mod = Module.new
+          settings.stack.each do |s|
+            mod.send :include, s[:helpers] if s[:helpers]
+          end
+          change!
+          mod
+        end
+      end
+
+      # Add an authentication type to the API. Currently
+      # only `:http_basic`, `:http_digest` and `:oauth2` are supported.
+      def auth(type = nil, options = {}, &block)
+        if type
+          set(:auth, { type: type.to_sym, proc: block }.merge(options))
+        else
+          settings[:auth]
+        end
+      end
+
+      # Add HTTP Basic authorization to the API.
+      #
+      # @param [Hash] options A hash of options.
+      # @option options [String] :realm "API Authorization" The HTTP Basic realm.
+      def http_basic(options = {}, &block)
+        options[:realm] ||= "API Authorization"
+        auth :http_basic, options, &block
+      end
+
+      def http_digest(options = {}, &block)
+        options[:realm] ||= "API Authorization"
+        options[:opaque] ||= "secret"
+        auth :http_digest, options, &block
+      end
+
+      def mount(mounts)
+        mounts = { mounts => '/' } unless mounts.respond_to?(:each_pair)
+        mounts.each_pair do |app, path|
+          if app.respond_to?(:inherit_settings, true)
+            app_settings = settings.clone
+            mount_path = Rack::Mount::Utils.normalize_path([settings[:mount_path], path].compact.join("/"))
+            app_settings.set :mount_path, mount_path
+            app.inherit_settings(app_settings)
+          end
+          endpoints << Grape::Endpoint.new(
+            settings.clone,
+            method: :any,
+            path: path,
+            app: app
+          )
+        end
+      end
+
+      # Defines a route that will be recognized
+      # by the Grape API.
+      #
+      # @param methods [HTTP Verb] One or more HTTP verbs that are accepted by this route. Set to `:any` if you want any verb to be accepted.
+      # @param paths [String] One or more strings representing the URL segment(s) for this route.
+      #
+      # @example Defining a basic route.
+      #   class MyAPI < Grape::API
+      #     route(:any, '/hello') do
+      #       {hello: 'world'}
+      #     end
+      #   end
+      def route(methods, paths = ['/'], route_options = {}, &block)
+        endpoint_options = {
+          method: methods,
+          path: paths,
+          route_options: (@namespace_description || {}).deep_merge(@last_description || {}).deep_merge(route_options || {})
+        }
+        endpoints << Grape::Endpoint.new(settings.clone, endpoint_options, &block)
+
+        @last_description = nil
+        reset_validations!
+      end
+
+      def before(&block)
+        imbue(:befores, [block])
+      end
+
+      def before_validation(&block)
+        imbue(:before_validations, [block])
+      end
+
+      def after_validation(&block)
+        imbue(:after_validations, [block])
+      end
+
+      def after(&block)
+        imbue(:afters, [block])
+      end
+
+      def get(paths = ['/'], options = {}, &block)
+        route('GET', paths, options, &block)
+      end
+
+      def post(paths = ['/'], options = {}, &block)
+        route('POST', paths, options, &block)
+      end
+
+      def put(paths = ['/'], options = {}, &block)
+        route('PUT', paths, options, &block)
+      end
+
+      def head(paths = ['/'], options = {}, &block)
+        route('HEAD', paths, options, &block)
+      end
+
+      def delete(paths = ['/'], options = {}, &block)
+        route('DELETE', paths, options, &block)
+      end
+
+      def options(paths = ['/'], options = {}, &block)
+        route('OPTIONS', paths, options, &block)
+      end
+
+      def patch(paths = ['/'], options = {}, &block)
+        route('PATCH', paths, options, &block)
+      end
+
+      def namespace(space = nil, options = {},  &block)
+        if space || block_given?
+          previous_namespace_description = @namespace_description
+          @namespace_description = (@namespace_description || {}).deep_merge(@last_description || {})
+          @last_description = nil
+          nest(block) do
+            set(:namespace, Namespace.new(space, options)) if space
+          end
+          @namespace_description = previous_namespace_description
+        else
+          Namespace.joined_space_path(settings)
+        end
+      end
+
+      # Thie method allows you to quickly define a parameter route segment
+      # in your API.
+      #
+      # @param param [Symbol] The name of the parameter you wish to declare.
+      # @option options [Regexp] You may supply a regular expression that the declared parameter must meet.
+      def route_param(param, options = {}, &block)
+        options = options.dup
+        options[:requirements] = { param.to_sym => options[:requirements] } if options[:requirements].is_a?(Regexp)
+        namespace(":#{param}", options, &block)
+      end
+
+      alias_method :group, :namespace
+      alias_method :resource, :namespace
+      alias_method :resources, :namespace
+      alias_method :segment, :namespace
+
+      # Create a scope without affecting the URL.
+      #
+      # @param name [Symbol] Purely placebo, just allows to to name the scope to make the code more readable.
+      def scope(name = nil, &block)
+        nest(block)
+      end
+
+      # Apply a custom middleware to the API. Applies
+      # to the current namespace and any children, but
+      # not parents.
+      #
+      # @param middleware_class [Class] The class of the middleware you'd like
+      #   to inject.
+      def use(middleware_class, *args, &block)
+        arr = [middleware_class, *args]
+        arr << block if block_given?
+        imbue(:middleware, [arr])
+      end
+
+      # Retrieve an array of the middleware classes
+      # and arguments that are currently applied to the
+      # application.
+      def middleware
+        settings.stack.inject([]) do |a, s|
+          a += s[:middleware] if s[:middleware]
+          a
+        end
+      end
+
+      # An array of API routes.
+      def routes
+        @routes ||= prepare_routes
+      end
+
+      def versions
+        @versions ||= []
+      end
+
+      def cascade(value = nil)
+        if value.nil?
+          settings.key?(:cascade) ? !!settings[:cascade] : true
+        else
+          set(:cascade, value)
+        end
+      end
+
+      protected
+
+      def prepare_routes
+        routes = []
+        endpoints.each do |endpoint|
+          routes.concat(endpoint.routes)
+        end
+        routes
+      end
+
+      # Execute first the provided block, then each of the
+      # block passed in. Allows for simple 'before' setups
+      # of settings stack pushes.
+      def nest(*blocks, &block)
+        blocks.reject! { |b| b.nil? }
+        if blocks.any?
+          settings.push  # create a new context to eval the follow
+          instance_eval(&block) if block_given?
+          blocks.each { |b| instance_eval(&b) }
+          settings.pop # when finished, we pop the context
+          reset_validations!
+        else
+          instance_eval(&block)
+        end
+      end
+
+      def inherited(subclass)
+        subclass.reset!
+        subclass.logger = logger.clone
+      end
+
+      def inherit_settings(other_stack)
+        settings.prepend other_stack
+        endpoints.each do |e|
+          e.settings.prepend(other_stack)
+          e.options[:app].inherit_settings(other_stack) if e.options[:app].respond_to?(:inherit_settings, true)
+        end
+      end
+
+      def inject_api_helpers_to_mod(mod, &block)
+        mod.extend(Helpers)
+        yield if block_given?
+        mod.api_changed(self)
+      end
+    end
+
+    def initialize
+      @route_set = Rack::Mount::RouteSet.new
+      add_head_not_allowed_methods_and_options_methods
+      self.class.endpoints.each do |endpoint|
+        endpoint.mount_in(@route_set)
+      end
+      @route_set.freeze
+    end
+
+    def call(env)
+      status, headers, body = @route_set.call(env)
+      headers.delete('X-Cascade') unless cascade?
+      [status, headers, body]
+    end
+
+    # Some requests may return a HTTP 404 error if grape cannot find a matching
+    # route. In this case, Rack::Mount adds a X-Cascade header to the response
+    # and sets it to 'pass', indicating to grape's parents they should keep
+    # looking for a matching route on other resources.
+    #
+    # In some applications (e.g. mounting grape on rails), one might need to trap
+    # errors from reaching upstream. This is effectivelly done by unsetting
+    # X-Cascade. Default :cascade is true.
+    def cascade?
+      return !!self.class.settings[:cascade] if self.class.settings.key?(:cascade)
+      return !!self.class.settings[:version_options][:cascade] if self.class.settings[:version_options] && self.class.settings[:version_options].key?(:cascade)
+      true
+    end
+
+    reset!
+
+    private
+
+    # For every resource add a 'OPTIONS' route that returns an HTTP 204 response
+    # with a list of HTTP methods that can be called. Also add a route that
+    # will return an HTTP 405 response for any HTTP method that the resource
+    # cannot handle.
+    def add_head_not_allowed_methods_and_options_methods
+      methods_per_path = {}
+      self.class.endpoints.each do |endpoint|
+        routes = endpoint.routes
+        routes.each do |route|
+          methods_per_path[route.route_path] ||= []
+          methods_per_path[route.route_path] << route.route_method
+        end
+      end
+
+      # The paths we collected are prepared (cf. Path#prepare), so they
+      # contain already versioning information when using path versioning.
+      # Disable versioning so adding a route won't prepend versioning
+      # informations again.
+      without_versioning do
+        methods_per_path.each do |path, methods|
+          allowed_methods = methods.dup
+          unless self.class.settings[:do_not_route_head]
+            allowed_methods |= ['HEAD'] if allowed_methods.include?('GET')
+          end
+
+          allow_header = (['OPTIONS'] | allowed_methods).join(', ')
+          unless self.class.settings[:do_not_route_options]
+            unless allowed_methods.include?('OPTIONS')
+              self.class.options(path, {}) do
+                header 'Allow', allow_header
+                status 204
+                ''
+              end
+            end
+          end
+
+          not_allowed_methods = %w(GET PUT POST DELETE PATCH HEAD) - allowed_methods
+          not_allowed_methods << 'OPTIONS' if self.class.settings[:do_not_route_options]
+          self.class.route(not_allowed_methods, path) do
+            header 'Allow', allow_header
+            status 405
+            ''
+          end
+        end
+      end
+    end
+
+    def without_versioning(&block)
+      self.class.settings.push(version: nil, version_options: nil)
+      yield
+      self.class.settings.pop
+    end
+
+    # This module extends user defined helpers
+    # to provide some API-specific functionality
+    module Helpers
+      attr_accessor :api
+      def params(name, &block)
+        @named_params ||= {}
+        @named_params.merge! name => block
+      end
+
+      def api_changed(new_api)
+        @api = new_api
+        process_named_params
+      end
+
+      protected
+
+      def process_named_params
+        if @named_params && @named_params.any?
+          api.imbue(:named_params, @named_params)
+        end
+      end
+    end
+  end
+end