grape 0.5.0 → 0.6.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    Y2ZhNWZiZWQ4YjIwNmY5MDk1NmQxODgxM2FiZDA0NTE3ZDlmZmNiYQ==
+  data.tar.gz: !binary |-
+    MTE5MjU2MWY2MWZlNGI1ODQzNDExMDZjOTNmZjRiYzc3ZDY4ODZlMg==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    MDlhYjA4YWQ1OThhMGFhNTc3ZjUwNzI4N2FiNmY2ZmNlOGM3MjQ5YjE2OWMy
+    NzcxODEwZmY3Y2I5ZmVkOTk5ZWViMTNkZmE3NGM3MjMyOTAzZTdmMTg5MWZm
+    ZmI1Njk0ZjRlMGIwOGFkY2EzZDJhZTMxMDQ0MzcyMDM4Y2UxMGY=
+  data.tar.gz: !binary |-
+    OWU4MGUxOGJkYzRjYzhkZmQyMzFkMWU1NTk3ZTllMTRkZDkyOTA0YjcwODg3
+    YWNiNWY0ZDQzZWUxNmI4MmYxZGQzOWJmMTFiZDg0YTFiNzMyYzA5ODBhMDYz
+    ZWRiN2FmY2FhM2FjNjQ1ZWM2NjMwNWI1YmU1Y2NhYjA1NGI2MDg=

data/.travis.yml

@@ -1,9 +1,5 @@
 rvm:
   - 2.0.0
-  - 1.8.7
-  - 1.9.2
   - 1.9.3
-  - jruby
-  - rbx
-  - ree
-
+  - jruby-19mode
+  - rbx-19mode

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+0.6.0 (9/16/2013)
+=================
+
+#### Features
+
+* Grape is no longer tested against Ruby 1.8.7.
+* [#442](https://github.com/intridea/grape/issues/442): Enable incrementally building on top of a previous API version - [@dblock](https://github.com/dblock).
+* [#442](https://github.com/intridea/grape/issues/442): API `version` can now take an array of multiple versions - [@dblock](https://github.com/dblock).
+* [#444](https://github.com/intridea/grape/issues/444): Added `:en` as fallback locale for I18n - [@aew](https://github.com/aew).
+* [#448](https://github.com/intridea/grape/pull/448): Adding POST style parameters for DELETE requests - [@dquimper](https://github.com/dquimper).
+* [#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).
+* Your contribution here.
+
+#### Fixes
+
+* [#428](https://github.com/intridea/grape/issues/428): Removes memoization from `Grape::Request` params to prevent middleware from freezing parameter values before `Formatter` can get them - [@mbleigh](https://github.com/mbleigh).
+
 0.5.0 (6/14/2013)
 =================
 

data/README.md

@@ -10,6 +10,10 @@ 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)
 
+## Stable Release
+
+You're reading the documentation for the stable release of Grape, 0.6.0.
+
 ## Project Resources
 
 * Need help? [Grape Google Group](http://groups.google.com/group/ruby-grape)
@@ -221,7 +225,7 @@ version 'v1', using: :header, vendor: 'twitter'
 
 Using this versioning strategy, clients should pass the desired version in the HTTP `Accept` head.
 
-    curl -H Accept=application/vnd.twitter-v1+json http://localhost:9292/statuses/public_timeline
+    curl -H Accept:application/vnd.twitter-v1+json http://localhost:9292/statuses/public_timeline
 
 By default, the first matching version is used when no `Accept` header is
 supplied. This behavior is similar to routing in Rails. To circumvent this default behavior,
@@ -236,7 +240,7 @@ version 'v1', using: :accept_version_header
 
 Using this versioning strategy, clients should pass the desired version in the HTTP `Accept-Version` header.
 
-    curl -H "Accept-Version=v1" http://localhost:9292/statuses/public_timeline
+    curl -H "Accept-Version:v1" http://localhost:9292/statuses/public_timeline
 
 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,
@@ -329,6 +333,9 @@ params do
   group :media do
     requires :url
   end
+  optional :audio do
+    requires :mp3
+  end
 end
 put ':id' do
   # params[:id] is an Integer
@@ -346,8 +353,9 @@ params do
 end
 ```
 
-Parameters can be nested using `group`. In the above example, this means
-`params[:media][:url]` is required along with `params[:id]`.
+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.
 
 ### Namespace Validation and Coercion
 
@@ -379,7 +387,7 @@ The `namespace` method has a number of aliases, including: `group`, `resource`,
 class AlphaNumeric < Grape::Validations::Validator
   def validate_param!(attr_name, params)
     unless params[attr_name] =~ /^[[:alnum:]]+$/
-      throw :error, status: 400, message: "#{attr_name}: must consist of alpha-numeric characters"
+      raise Grape::Exceptions::Validation, param: @scope.full_name(attr_name), message: "must consist of alpha-numeric characters"
     end
   end
 end
@@ -397,7 +405,7 @@ You can also create custom classes that take parameters.
 class Length < Grape::Validations::SingleOptionValidator
   def validate_param!(attr_name, params)
     unless params[attr_name].length <= @option
-      throw :error, status: 400, message: "#{attr_name}: must be at the most #{@option} characters long"
+      raise Grape::Exceptions::Validation, param: @scope.full_name(attr_name), message: "must be at the most #{@option} characters long"
     end
   end
 end
@@ -411,20 +419,28 @@ end
 
 ### Validation Errors
 
-When validation and coercion errors occur an exception of type `Grape::Exceptions::Validation` is raised.
+Validation and coercion errors are collected and an exception of type `Grape::Exceptions::ValidationErrors` is raised.
 If the exception goes uncaught it will respond with a status of 400 and an error message.
-You can rescue a `Grape::Exceptions::Validation` and respond with a custom response.
+You can rescue a `Grape::Exceptions::ValidationErrors` and respond with a custom response.
 
 ```ruby
-rescue_from Grape::Exceptions::Validation do |e|
+rescue_from Grape::Exceptions::ValidationErrors do |e|
     Rack::Response.new({
         'status' => e.status,
         'message' => e.message,
-        'param' => e.param
+        'errors' => e.errors
     }.to_json, e.status)
 end
 ```
 
+The validation errors are grouped by parameter name and can be accessed via ``Grape::Exceptions::ValidationErrors#errors``.
+
+### I18n
+
+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.
@@ -629,9 +645,23 @@ 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)
 ```
 
+### Handling 404
+
+For Grape to handle all the 404s for your API, it can be useful to use a catch-all.
+In its simplest form, it can be like:
+
+```ruby
+route :any, '*path' do
+  error! # or something else
+end
+```
+
+It is very crucial to __define this endpoint at the very end of your API__, as it
+literally accepts every request.
+
 ## Exception Handling
 
 Grape can be told to rescue all exceptions and return them in the API format.
@@ -1045,6 +1075,8 @@ 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

data/lib/grape.rb

@@ -22,8 +22,12 @@ 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'
@@ -31,6 +35,7 @@ module Grape
   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'
@@ -70,6 +75,7 @@ module Grape
 
     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

data/lib/grape/api.rb

@@ -6,14 +6,8 @@ module Grape
     extend Validations::ClassMethods
 
     class << self
-      attr_reader :route_set
-      attr_reader :versions
-      attr_reader :routes
-      attr_reader :settings
+      attr_reader :endpoints, :instance, :routes, :route_set, :settings, :versions
       attr_writer :logger
-      attr_reader :endpoints
-      attr_reader :mountings
-      attr_reader :instance
 
       def logger(logger = nil)
         if logger
@@ -27,7 +21,6 @@ module Grape
         @settings  = Grape::Util::HashStack.new
         @route_set = Rack::Mount::RouteSet.new
         @endpoints = []
-        @mountings = []
         @routes = nil
         reset_validations!
       end
@@ -158,8 +151,14 @@ module Grape
         new_formatter ? set(:default_error_formatter, new_formatter) : settings[:default_error_formatter]
       end
 
-      def error_formatter(format, new_formatter)
-        settings.imbue(:error_formatters, format.to_sym => new_formatter)
+      def error_formatter(format, options)
+        if options.is_a?(Hash) && options.has_key?(:with)
+          formatter = options[:with]
+        else
+          formatter = options
+        end
+
+        settings.imbue(:error_formatters, format.to_sym => formatter)
       end
 
       # Specify additional content-types, e.g.:
@@ -195,13 +194,27 @@ module Grape
       #   @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.
+      #   @param [Proc] handler Execution proc to handle the given exception as an
+      #     alternative to passing a block
       def rescue_from(*args, &block)
-        if block_given?
+        if args.last.is_a?(Proc)
+          handler = args.pop
+        elsif block_given?
+          handler = block
+        end
+
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        if options.has_key?(:with)
+          handler ||= proc { options[:with] }
+        end
+
+        if handler
           args.each do |arg|
-            imbue(:rescue_handlers, { arg => block })
+            imbue(:rescue_handlers, { arg => handler })
           end
         end
-        imbue(:rescue_options, args.pop) if args.last.is_a?(Hash)
+
+        imbue(:rescue_options, options)
         set(:rescue_all, true) and return if args.include?(:all)
         imbue(:rescued_errors, args)
       end
@@ -422,7 +435,7 @@ module Grape
       end
 
       def cascade(value = nil)
-        value.nil? ? 
+        value.nil? ?
           (settings.has_key?(:cascade) ? !! settings[:cascade] : true) :
           set(:cascade, value)
       end

data/lib/grape/endpoint.rb

@@ -33,27 +33,34 @@ module Grape
     end
 
     def initialize(settings, options = {}, &block)
+      require_option(options, :path)
+      require_option(options, :method)
+
       @settings = settings
+      @options = options
+
+      @options[:path] = Array(options[:path])
+      @options[:path] << '/' if options[:path].empty?
+
+      @options[:method] = Array(options[:method])
+      @options[:route_options] ||= {}
+
       if block_given?
-        method_name = [
-          options[:method],
-          Namespace.joined_space(settings),
-          settings.gather(:mount_path).join("/"),
-          Array(options[:path]).join("/")
-        ].join(" ")
         @source = block
         @block = self.class.generate_api_method(method_name, &block)
       end
-      @options = options
-
-      raise Grape::Exceptions::MissingOption.new(:path) unless options.key?(:path)
-      options[:path] = Array(options[:path])
-      options[:path] = ['/'] if options[:path].empty?
+    end
 
-      raise Grape::Exceptions::MissingOption.new(:method) unless options.key?(:method)
-      options[:method] = Array(options[:method])
+    def require_option(options, key)
+      options.has_key?(key) or raise Grape::Exceptions::MissingOption.new(key)
+    end
 
-      options[:route_options] ||= {}
+    def method_name
+      [ options[:method],
+        Namespace.joined_space(settings),
+        settings.gather(:mount_path).join('/'),
+        options[:path].join('/')
+      ].join(" ")
     end
 
     def routes
@@ -120,24 +127,7 @@ module Grape
     end
 
     def prepare_path(path)
-      parts = []
-      parts << settings[:mount_path].to_s.split("/") if settings[:mount_path]
-      parts << settings[:root_prefix].to_s.split("/") if settings[:root_prefix]
-
-      uses_path_versioning = settings[:version] && settings[:version_options][:using] == :path
-      namespace_is_empty = namespace && (namespace.to_s =~ /^\s*$/ || namespace.to_s == '/')
-      path_is_empty = path && (path.to_s =~ /^\s*$/ || path.to_s == '/')
-
-      parts << ':version' if uses_path_versioning
-      if ! uses_path_versioning || (! namespace_is_empty || ! path_is_empty)
-        parts << namespace.to_s if namespace
-        parts << path.to_s if path
-        format_suffix = '(.:format)'
-      else
-        format_suffix = '(/.:format)'
-      end
-      parts = parts.flatten.select { |part| part != '/' }
-      Rack::Mount::Utils.normalize_path(parts.join('/') + format_suffix)
+      Path.prepare(path, namespace, settings)
     end
 
     def namespace
@@ -391,8 +381,17 @@ module Grape
       run_filters befores
 
       # Retieve validations from this namespace and all parent namespaces.
+      validation_errors = []
       settings.gather(:validations).each do |validator|
-        validator.validate!(params)
+        begin
+          validator.validate!(params)
+        rescue Grape::Exceptions::Validation => e
+          validation_errors << e
+        end
+      end
+
+      if validation_errors.any?
+        raise Grape::Exceptions::ValidationErrors, errors: validation_errors
       end
 
       run_filters after_validations
@@ -433,7 +432,7 @@ module Grape
 
       if settings[:version]
         b.use Grape::Middleware::Versioner.using(settings[:version_options][:using]), {
-          :versions        => settings[:version],
+          :versions        => settings[:version] ? settings[:version].flatten : nil,
           :version_options => settings[:version_options],
           :prefix          => settings[:root_prefix]
         }

data/lib/grape/exceptions/base.rb

@@ -4,6 +4,7 @@ module Grape
 
       BASE_MESSAGES_KEY = 'grape.errors.messages'
       BASE_ATTRIBUTES_KEY = 'grape.errors.attributes'
+      FALLBACK_LOCALE = :en
 
       attr_reader :status, :message, :headers
 
@@ -54,11 +55,12 @@ module Grape
       end
 
       def translate_message(key, options = {})
-        translate("#{BASE_MESSAGES_KEY}.#{key}", {:default => '' }.merge(options))
+        translate("#{BASE_MESSAGES_KEY}.#{key}", { :default => '' }.merge(options))
       end
 
       def translate(key, options = {})
-        ::I18n.translate(key, options)
+        message = ::I18n.translate(key, options)
+        message.present? ? message : ::I18n.translate(key, options.merge({:locale => FALLBACK_LOCALE}))
       end
 
     end

data/lib/grape/exceptions/validation.rb

@@ -6,11 +6,21 @@ module Grape
       attr_accessor :param
 
       def initialize(args = {})
-        @param = args[:param].to_s if args.has_key? :param
-        attribute = translate_attribute(@param)
-        args[:message] = translate_message(args[:message_key], :attribute => attribute)
+        raise "Param is missing:" unless args.has_key? :param
+        @param = args[:param]
+        args[:message] = translate_message(args[:message_key]) if args.has_key? :message_key
         super
       end
+
+      # remove all the unnecessary stuff from Grape::Exceptions::Base like status
+      # and headers when converting a validation error to json or string
+      def as_json(*a)
+        self.to_s
+      end
+
+      def to_s
+        message
+      end
     end
   end
 end

data/lib/grape/exceptions/validation_errors.rb

@@ -0,0 +1,42 @@
+require 'grape/exceptions/base'
+
+module Grape
+  module Exceptions
+    class ValidationErrors < Grape::Exceptions::Base
+      include Enumerable
+
+      attr_reader :errors
+
+      def initialize(args = {})
+        @errors = {}
+        args[:errors].each do |validation_error|
+          @errors[validation_error.param] ||= []
+          @errors[validation_error.param] << validation_error
+        end
+        super message: full_messages.join(', '), status: 400
+      end
+
+      def each
+        errors.each_pair do |attribute, errors|
+          errors.each do |error|
+            yield attribute, error
+          end
+        end
+      end
+
+      private
+
+      def full_messages
+        map { |attribute, error| full_message(attribute, error) }
+      end
+
+      def full_message(attribute, error)
+        I18n.t(:"grape.errors.format", {
+          default:  "%{attribute} %{message}",
+          attribute: translate_attribute(attribute),
+          message:   error.message
+        })
+      end
+    end
+  end
+end