Merge remote branch 'upstream/master'

Author: fx

.gitignore

@@ -16,6 +16,7 @@ tmtags
 
 ## VIM
 *.swp
+*.swo
 
 ## RUBYMINE
 .idea

CHANGELOG.markdown

@@ -1,14 +1,24 @@
-Next Release
-============
+0.2.2 (Next Release)
+====================
 
-* [#201](https://github.com/intridea/grape/pull/201): Added custom exceptions to Grape. Updated validations to use ValidationError that can be rescued. - [@adamgotterer](https://github.com/adamgotterer).
-* [#211](https://github.com/intridea/grape/pull/211): Updates to validation and coercion: Fix #211 and force order of operations for presence and coercion - [@adamgotterer](https://github.com/adamgotterer).
+Features
+--------
+
+* [#201](https://github.com/intridea/grape/pull/201), [#236](https://github.com/intridea/grape/pull/236), [#221](https://github.com/intridea/grape/pull/221): Added coercion and validations support to `params` DSL - [@schmurfy](https://github.com/schmurfy), [@tim-vandecasteele](https://github.com/tim-vandecasteele), [@adamgotterer](https://github.com/adamgotterer).
+* [#204](https://github.com/intridea/grape/pull/204): Added ability to declare shared `params` at `namespace` level - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
+* [#234](https://github.com/intridea/grape/pull/234): Added a DSL for creating entities via mixin - [@mbleigh](https://github.com/mbleigh).
+* [#240](https://github.com/intridea/grape/pull/240): Define API response format from a query string `format` parameter, if specified - [@neetiraj](https://github.com/neetiraj).
+
+Fixes
+-----
+
+* [#248](https://github.com/intridea/grape/pull/248): Fix: API `version` returns last version set - [@narkoz](https://github.com/narkoz).
+* [#242](https://github.com/intridea/grape/issues/242): Fix: permanent redirect status should be `301`, was `304` - [@adamgotterer](https://github.com/adamgotterer).
+* [#211](https://github.com/intridea/grape/pull/211): Fix: custom validations are no longer triggered when optional and parameter is not present - [@adamgotterer](https://github.com/adamgotterer).
 * [#210](https://github.com/intridea/grape/pull/210): Fix: `Endpoint#body_params` causing undefined method 'size' - [@adamgotterer](https://github.com/adamgotterer).
-* [#201](https://github.com/intridea/grape/pull/201): Rewritten `params` DSL, including support for coercion and validations - [@schmurfy](https://github.com/schmurfy).
 * [#205](https://github.com/intridea/grape/pull/205): Fix: Corrected parsing of empty JSON body on POST/PUT - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
 * [#181](https://github.com/intridea/grape/pull/181): Fix: Corrected JSON serialization of nested hashes containing `Grape::Entity` instances - [@benrosenblum](https://github.com/benrosenblum).
 * [#203](https://github.com/intridea/grape/pull/203): Added a check to `Entity#serializable_hash` that verifies an entity exists on an object - [@adamgotterer](https://github.com/adamgotterer).
-* [#204](https://github.com/intridea/grape/pull/204): Added ability to declare shared parameters at namespace level - [@tim-vandecasteele](https://github.com/tim-vandecasteele).
 * [#208](https://github.com/intridea/grape/pull/208): `Entity#serializable_hash` must also check if attribute is generated by a user supplied block - [@ppadron](https://github.com/ppadron).
 
 0.2.1 (7/11/2012)

README.markdown

@@ -2,11 +2,11 @@
 
 ## What is Grape?
 
-Grape is a REST-like API micro-framework for Ruby. It's built to 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, content
-negotiation, versioning and much more.
+Grape is a REST-like API micro-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, 
+content negotiation, versioning and much more.
 
 [![Build Status](http://travis-ci.org/intridea/grape.png?branch=master)](http://travis-ci.org/intridea/grape)
 
@@ -41,6 +41,7 @@ the context of recreating parts of the Twitter API.
 ``` ruby
 class Twitter::API < Grape::API
   version 'v1', :using => :header, :vendor => 'twitter'
+  format :json
 
   helpers do
     def current_user
@@ -214,12 +215,17 @@ end
 
 ## Parameter Validation and Coercion
 
-You can define validations and coercion options for your parameters using `params`.
+You can define validations and coercion options for your parameters using a `params` block.
 
 ```ruby
 params do
   requires :id, type: Integer
   optional :name, type: String, regexp: /^[a-z]+$/
+
+  group :user do
+    requires :first_name
+    requires :last_name
+  end
 end
 get ':id' do
   # params[:id] is an Integer
@@ -229,6 +235,9 @@ end
 When a type is specified an implicit validation is done after the coercion to ensure 
 the output type is the one declared.
 
+Parameters can be nested using `group`. In the above example, this means both
+`params[:user][:first_name]` and `params[:user][:last_name]` are required next to `params[:id]`.
+
 ### Namespace Validation and Coercion
 Namespaces allow parameter definitions and apply to every method within the namespace.
 
@@ -252,22 +261,23 @@ end
 
 ### Custom Validators
 ```ruby
-class doit < Grape::Validations::Validator
+class AlphaNumeric < Grape::Validations::Validator
   def validate_param!(attr_name, params)
-    unless params[attr_name] == 'im custom'
-      throw :error, :status => 400, :message => "#{attr_name}: is not custom!"
+    unless params[attr_name] =~ /^[[:alnum:]]+$/
+      throw :error, :status => 400, :message => "#{attr_name}: must consist of alpha-numeric characters"
     end    
   end
 end  
 ```
 
 ```ruby
 params do
-  requires :name, :doit => true
+  requires :username, :alpha_numeric => true
 end
 ```
 
-You can also create custom classes that take additional parameters
+You can also create custom classes that take parameters.
+
 ```ruby
 class Length < Grape::Validations::SingleOptionValidator
   def validate_param!(attr_name, params)
@@ -284,7 +294,21 @@ params do
 end
 ```
 
+### Validation Errors
+
+When validation and coercion erros occur an exception of type `ValidationError` is raised.
+If the exception goes uncaught it will respond with a status of 400 and an error message.
+You can rescue a `ValidationError` and respond with a custom response.
 
+```ruby
+rescue_from ValidationError do |e|
+    Rack::Response.new({
+        'status' => e.status,
+        'message' => e.message,
+        'param' => e.param
+    }.to_json, e.status)    
+end 
+```
 
 ## Headers
 
@@ -318,7 +342,7 @@ end
 ## Helpers
 
 You can define helper methods that your endpoints can use with the `helpers`
-macro by either giving a block or a module:
+macro by either giving a block or a module.
 
 ``` ruby
 module MyHelpers
@@ -347,7 +371,7 @@ end
 
 ## Cookies
 
-You can set, get and delete your cookies very simply using `cookies` method:
+You can set, get and delete your cookies very simply using `cookies` method.
 
 ``` ruby
 class API < Grape::API
@@ -363,7 +387,7 @@ class API < Grape::API
 end
 ```
 
-To set more than value use hash-based syntax:
+To set more than value use hash-based syntax.
 
 ``` ruby
 cookies[:counter] = {
@@ -377,7 +401,7 @@ cookies[:counter][:value] +=1
 
 ## Redirecting
 
-You can redirect to a new url temporarily or permanently.
+You can redirect to a new url temporarily (302) or permanently (301).
 
 ``` ruby
 redirect "/new_url"
@@ -405,7 +429,7 @@ error!({ "error" => "unexpected error", "detail" => "missing widget" }, 500)
 ## Exception Handling
 
 Grape can be told to rescue all exceptions and instead return them in
-text or json formats.
+txt or json formats.
 
 ``` ruby
 class Twitter::API < Grape::API
@@ -516,7 +540,7 @@ By default, Grape supports _XML_, _JSON_, _Atom_, _RSS_, and _text_ content-type
 Serialization takes place automatically.
 
 Your API can declare additional types to support. Response format is determined by the
-request's extension or `Accept` header.
+request's extension, an explicit `format` parameter in the query string, or `Accept` header.
 
 ``` ruby
 class Twitter::API < Grape::API
@@ -527,7 +551,8 @@ end
 You can also set the default format. The order for choosing the format is the following.
 
 * Use the file extension, if specified. If the file is .json, choose the JSON format.
-* Use the format, if specified by the `format` option.
+* Use the value of the `format` parameter in the query string, if specified.
+* Use the format set by the `format` option, if specified.
 * Attempt to find an acceptable format from the `Accept` header.
 * Use the default format, if specified by the `default_format` option.
 * Default to `:txt` otherwise.
@@ -560,22 +585,22 @@ ever larger responses, using inheritance.
 
 Entities inherit from Grape::Entity, and define a simple DSL. Exposures can use
 runtime options to determine which fields should be visible, these options are
-available to :if, :unless, and :proc. The option keys :version and :collection
-will always be defined. The :version key is defined as api.version. The
-:collection key is boolean, and defined as true if the object presented is an
+available to `:if`, `:unless`, and `:proc`. The option keys `:version` and `:collection`
+will always be defined. The `:version` key is defined as `api.version`. The
+`:collection` key is boolean, and defined as `true` if the object presented is an
 array.
 
   * `expose SYMBOLS`
     * define a list of fields which will always be exposed
   * `expose SYMBOLS, HASH`
-    * HASH keys include :if, :unless, :proc, :as, :using, :format_with, :documentation
-      * :if and :unless accept hashes (passed during runtime) or procs (arguments are object and options)
-  * `expose SYMBOL, {:format_with => :formatter}`
+    * HASH keys include `:if`, `:unless`, `:proc`, `:as`, `:using`, `:format_with`, `:documentation`
+      * `:if` and `:unless` accept hashes (passed during runtime) or procs (arguments are object and options)
+  * `expose SYMBOL, { :format_with => :formatter }`
     * expose a value, formatting it first
-    * :format_with can only be applied to one exposure at a time
-  * `expose SYMBOL, {:as => "alias"}`
+    * `:format_with` can only be applied to one exposure at a time
+  * `expose SYMBOL, { :as => "alias" }`
     * Expose a value, changing its hash key from SYMBOL to alias
-    * :as can only be applied to one exposure at a time
+    * `:as` can only be applied to one exposure at a time
   * `expose SYMBOL BLOCK`
     * block arguments are object and options
     * expose the value returned by the block
@@ -586,10 +611,10 @@ module API
   module Entities
     class User < Grape::Entity
       expose :first_name, :last_name
-      expose :field, :documentation => {:type => "string", :desc => "words go here"}
-      expose :email, :if => {:type => :full}
-      expose :user_type, user_id, :if => lambda{|user,options| user.confirmed?}
-      expose(:name){|user,options| [user.first_name, user.last_name].join(' ')}
+      expose :field, :documentation => { :type => "string", :desc => "words go here" }
+      expose :email, :if => { :type => :full }
+      expose :user_type, user_id, :if => lambda{ |user,options| user.confirmed? }
+      expose(:name) { |user,options| [ user.first_name, user.last_name ].join(' ')}
       expose :latest_status, :using => API::Status, :as => :status
     end
   end
@@ -604,11 +629,32 @@ module API
 end
 ```
 
+#### Using the Exposure DSL
+
+Grape ships with a DSL to easily define entities within the context
+of an existing class:
+
+```ruby
+class User
+  include Grape::Entity::DSL
+
+  entity :name, :email do
+    expose :advanced, if: :conditional
+  end
+end
+```
+
+The above will automatically create a `User::Entity` class and
+define properties on it according to the same rules as above. If
+you only want to define simple exposures you don't have to supply
+a block and can instead simply supply a list of comma-separated
+symbols.
+
 ### Using Entities
 
-Once an entity is defined, it can be used within endpoints, by calling #present. The #present
+Once an entity is defined, it can be used within endpoints, by calling `present`. The `present`
 method accepts two arguments, the object to be presented and the options associated with it. The
-options hash must always include :with, which defines the entity to expose.
+options hash must always include `:with`, which defines the entity to expose.
 
 If the entity includes documentation it can be included in an endpoint's description.
 
@@ -629,32 +675,58 @@ module API
 end
 ```
 
+### Entity Organization
+
+In addition to separately organizing entities, it may be useful to
+put them as namespaced classes underneath the model they represent.
+For example:
+
+```ruby
+class User
+  def entity
+    Entity.new(self)
+  end
+
+  class Entity < Grape::Entity
+    expose :name, :email
+  end
+end
+```
+
+If you organize your entities this way, Grape will automatically
+detect the `Entity` class and use it to present your models. In
+this example, if you added `present User.new` to your endpoint,
+Grape would automatically detect that there is a `User::Entity`
+class and use that as the representative entity. This can still
+be overridden by using the `:with` option or an explicit
+`represents` call.
+
 ### Caveats
 
 Entities with duplicate exposure names and conditions will silently overwrite one another.
-In the following example, when object#check equals "foo", only afield will be exposed.
-However, when object#check equals "bar" both bfield and foo will be exposed.
+In the following example, when `object.check` equals "foo", only `field_a` will be exposed.
+However, when `object.check` equals "bar" both `field_b` and `foo` will be exposed.
 
 ```ruby
 module API
   module Entities
     class User < Grape::Entity
-      expose :afield, :foo, :if => lambda{|object,options| object.check=="foo"}
-      expose :bfield, :foo, :if => lambda{|object,options| object.check=="bar"}
+      expose :field_a, :foo, :if => lambda { |object, options| object.check == "foo" }
+      expose :field_b, :foo, :if => lambda { |object, options| object.check == "bar" }
     end
   end
 end
 ```
 
-This can be problematic, when you have mixed collections. Using #respond_to? is safer.
+This can be problematic, when you have mixed collections. Using `respond_to?` is safer.
 
 ```ruby
 module API
   module Entities
     class User < Grape::Entity
-      expose :afield, :if => lambda{|object,options| object.check=="foo"}
-      expose :bfield, :if => lambda{|object,options| object.check=="bar"}
-      expose :foo, :if => lambda{object,options| object.respond_to?(:foo)}
+      expose :field_a, :if => lambda { |object, options| object.check == "foo" }
+      expose :field_b, :if => lambda { |object, options| object.check == "bar" }
+      expose :foo, :if => lambda { |object, options| object.respond_to?(:foo) }
     end
   end
 end
@@ -793,19 +865,21 @@ RSpec.configure do |config|
 end
 ```
 
-## Note on Patches/Pull Requests
+## Contributing to Grape
+
+Grape is work of dozens 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
 * Do not mess with Rakefile, version or history
-* Commit, push and make a pull request. Bonus points for topical branches.
+* Commit, push and make a pull request. Bonus points for topic branches.
 
 ## License
 
 MIT License. See LICENSE for details.
 
 ## Copyright
 
-Copyright (c) 2010-2012 Michael Bleigh and Intridea, Inc.
-
+Copyright (c) 2010-2012 Michael Bleigh, and Intridea, Inc.

grape.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'rack'
   s.add_runtime_dependency 'rack-mount'
   # s.add_runtime_dependency 'rack-jsonp'
-  s.add_runtime_dependency 'multi_json'
+  s.add_runtime_dependency 'multi_json', '>= 1.3.2'
   s.add_runtime_dependency 'multi_xml'
   s.add_runtime_dependency 'hashie'
   s.add_runtime_dependency 'virtus'