Merge branch 'master' of https://github.com/intridea/grape

Author: Ben Rosenblum

CHANGELOG.markdown

@@ -0,0 +1,63 @@
+Next Release
+============
+
+* [#64](https://github.com/intridea/grape/issues/64), [#180](https://github.com/intridea/grape/pull/180): Added support to get request bodies as parameters - [@bobbytables](https://github.com/bobbytables).
+* [#175](https://github.com/intridea/grape/pull/175): Added support for API versioning based on a request parameter - [@jackcasey](https://github.com/jackcasey).
+* [#168](https://github.com/intridea/grape/pull/168): Fix: Formatter can parse symbol keys in the headers hash - [@netmask](https://github.com/netmask).
+* [#169](https://github.com/intridea/grape/pull/169): Silence multi_json deprecation warnings - [@whiteley](https://github.com/whiteley).
+* [#166](https://github.com/intridea/grape/pull/166): Added support for `redirect`, including permanent and temporary - [@allenwei](https://github.com/allenwei).
+* [#159](https://github.com/intridea/grape/pull/159): Added `:requirements` to routes, allowing to use reserved characters in paths - [@gaiottino](https://github.com/gaiottino).
+* [#156](https://github.com/intridea/grape/pull/156): Added support for adding formatters to entities - [@bobbytables](https://github.com/bobbytables).
+
+0.2.0 (3/28/2012)
+=================
+
+* Added support for inheriting exposures from entities - [@bobbytables](https://github.com/bobbytables).
+* Extended formatting with `default_format` - [@dblock](https://github.com/dblock).
+* Added support for cookies - [@lukaszsliwa](https://github.com/lukaszsliwa).
+* Added support for declaring additional content-types - [@joeyAghion](https://github.com/joeyAghion).
+* Added support for HTTP PATCH - [@LTe](https://github.com/LTe).
+* Added support for describing, documenting and reflecting APIs - [@dblock](https://github.com/dblock).
+* Added support for anchoring and vendoring - [@jwkoelewijn](https://github.com/jwkoelewijn).
+* Added support for HTTP OPTIONS - [@grimen](https://github.com/grimen).
+* Added support for silencing logger - [@evansj](https://github.com/evansj).
+* Added support for helper modules - [@freelancing-god](https://github.com/freelancing-god).
+* Added support for Accept header-based versioning - [@jch](https://github.com/jch), [@rodzyn](https://github.com/rodzyn).
+* Added support for mounting APIs and other Rack applications within APIs - [@mbleigh](https://github.com/mbleigh).
+* Added entities, multiple object representations - [@mbleigh](https://github.com/mbleigh).
+* Added ability to handle XML in the incoming request body - [@jwillis](https://github.com/jwillis).
+* Added support for a configurable logger - [@mbleigh](https://github.com/mbleigh).
+* Added support for before and after filters - [@mbleigh](https://github.com/mbleigh).
+* Extended `rescue_from`, which can now take a block - [@dblock](https://github.com/dblock).
+
+
+0.1.5 (6/14/2011)
+==================
+
+* Extended exception handling to all exceptions - [@dblock](https://github.com/dblock).
+* Added support for returning JSON objects from within error blocks - [@dblock](https://github.com/dblock).
+* Added support for handling incoming JSON in body - [@tedkulp](https://github.com/tedkulp).
+* Added support for HTTP digest authentication - [@daddz](https://github.com/daddz).
+
+0.1.4 (4/8/2011)
+==================
+
+* Allow multiple definitions of the same endpoint under multiple versions - [@chrisrhoden](https://github.com/chrisrhoden).
+* Added support for multipart URL parameters - [@mcastilho](https://github.com/mcastilho).
+* Added support for custom formatters - [@spraints](https://github.com/spraints).
+
+0.1.3 (1/10/2011)
+==================
+
+* Added support for JSON format in route matching - [@aiwilliams](https://github.com/aiwilliams).
+* Added suport for custom middleware - [@mbleigh](https://github.com/mbleigh).
+
+0.1.1 (11/14/2010)
+==================
+
+* Endpoints properly reset between each request - [@mbleigh](https://github.com/mbleigh).
+
+0.1.0 (11/13/2010)
+==================
+
+* Initial public release - [@mbleigh](https://github.com/mbleigh).

README.markdown

@@ -110,10 +110,14 @@ end
 
 ## Versioning
 
-There are two strategies in which clients can reach your API's endpoints: `:header` 
-and `:path`. The default strategy is `:header`.
+There are three strategies in which clients can reach your API's endpoints: `:header`, `:path` and `:param`. The default strategy is `:header`.
 
-    version 'v1', :using => :header
+
+### Header
+
+```ruby
+version 'v1', :using => :header
+```
 
 Using this versioning strategy, clients should pass the desired version in the HTTP Accept head. 
 
@@ -124,34 +128,70 @@ 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 `404 Not found` error
 is returned when no correct Accept header is supplied.
 
-    version 'v1', :using => :path
+### Path
+
+``` ruby
+version 'v1', :using => :path
+```
 
 Using this versioning strategy, clients should pass the desired version in the URL.
 
     curl -H http://localhost:9292/v1/statuses/public_timeline
 
 Serialization takes place automatically. 
 
+### Param
+
+```ruby
+version 'v1', :using => :param
+```
+
+Using this versioning strategy, clients should pass the desired version as a request parameter, either in the URL query string or in the request body. 
+
+    curl -H http://localhost:9292/events?apiver=v1
+
+The default name for the query parameter is 'apiver' but can be specified using the :parameter option.
+
+```ruby
+version 'v1', :using => :param, :parameter => "v"
+```
+
+    curl -H http://localhost:9292/events?v=v1
+
 ## Parameters
 
 Parameters are available through the `params` hash object. This includes `GET` and `POST` parameters, 
 along with any named parameters you specify in your route strings.
 
 ```ruby
-  get do
+get do
     Article.order(params[:sort_by])
-  end
+end
+```
+
+Parameters are also populated from the request body on POST and PUT for JSON and XML content-types.
+
+The Request:
+
+```curl -d '{"some_key": "some_value"}' 'http://localhost:9292/json_endpoint' -H Content-Type:application/json -v```
+
+The Grape Endpoint:
+
+```ruby
+post '/json_endpoint' do
+    params[:some_key]
+end
 ```
 
 ## Headers
 
 Headers are available through the `env` hash object.
 
 ```ruby
-  get do
+get do
     error! 'Unauthorized', 401 unless env['HTTP_SECRET_PASSWORD'] == 'swordfish'
     ...
-  end
+end
 ```
 
 ## Helpers

lib/grape.rb

@@ -26,6 +26,7 @@ module Auth
     module Versioner
       autoload :Path,   'grape/middleware/versioner/path'
       autoload :Header, 'grape/middleware/versioner/header'
+      autoload :Param,  'grape/middleware/versioner/param'
     end
   end
 

lib/grape/endpoint.rb

@@ -118,7 +118,26 @@ def call!(env)
     # The parameters passed into the request as
     # well as parsed from URL segments.
     def params
-      @params ||= Hashie::Mash.new.deep_merge(request.params).deep_merge(env['rack.routing_args'] || {})
+      @params ||= Hashie::Mash.new.
+        deep_merge(request.params).
+        deep_merge(env['rack.routing_args'] || {}).
+        deep_merge(self.body_params)
+    end
+
+    # Pull out request body params if the content type matches and we're on a POST or PUT
+    def body_params
+      if ['POST', 'PUT'].include?(request.request_method.to_s.upcase)
+        return case env['CONTENT_TYPE']
+          when 'application/json'
+            MultiJson.decode(request.body.read)
+          when 'application/xml'
+            MultiXml.parse(request.body.read)
+          else
+            {}
+          end
+      end
+
+      {}
     end
 
     # The API version as specified in the URL.

lib/grape/middleware/versioner.rb

@@ -18,6 +18,8 @@ def using(strategy)
           Path
         when :header
           Header
+        when :param
+          Param
         else
           raise ArgumentError.new("Unknown :using for versioner: #{strategy}")
         end

lib/grape/middleware/versioner/param.rb

@@ -0,0 +1,44 @@
+require 'grape/middleware/base'
+
+module Grape
+  module Middleware
+    module Versioner
+      # This middleware sets various version related rack environment variables
+      # based on the request parameters and removes that parameter from the 
+      # request parameters for subsequent middleware and API.
+      # If the version substring does not match any potential initialized
+      # versions, a 404 error is thrown.
+      # If the version substring is not passed the version (highest mounted)
+      # version will be used.
+      # 
+      # Example: For a uri path
+      #   /resource?apiver=v1
+      # 
+      # The following rack env variables are set and path is rewritten to
+      # '/resource':
+      # 
+      #   env['api.version'] => 'v1'
+      class Param < Base
+        def default_options
+          {
+            :parameter => "apiver"
+          }
+        end
+
+        def before
+          paramkey = options[:parameter]
+          potential_version = request.params[paramkey]
+
+          unless potential_version.nil?
+            if options[:versions] && !options[:versions].include?(potential_version)
+              throw :error, :status => 404, :message => "404 API Version Not Found", :headers => {'X-Cascade' => 'pass'}
+            end
+            env['api.version'] = potential_version
+            env['rack.request.query_hash'].delete(paramkey)
+          end
+        end
+
+      end
+    end
+  end
+end

spec/grape/api_spec.rb

@@ -31,6 +31,17 @@ def app; subject end
     end
   end
 
+  describe '.version using param' do
+    it_should_behave_like 'versioning' do
+      let(:macro_options) do
+        {
+          :using => :param,
+          :parameter => "apiver"
+        }
+      end
+    end
+  end
+
   describe '.version using header' do
     it_should_behave_like 'versioning' do
       let(:macro_options) do

spec/grape/endpoint_spec.rb

@@ -167,7 +167,45 @@ def app; subject end
 
         get '[email protected]/wrong_middle/1'
         last_response.status.should == 404
+      end
+    end
+
+    context 'from body parameters' do
+      before(:each) do
+        subject.post '/request_body' do
+          params[:user]
+        end
+
+        subject.put '/request_body' do
+          params[:user]
+        end
+      end
+
+      it 'should convert JSON bodies to params' do
+        post '/request_body', MultiJson.encode(user: 'Bobby T.'), {'CONTENT_TYPE' => 'application/json'}
+        last_response.body.should == 'Bobby T.'
+      end
+
+      it 'should convert JSON bodies to params' do
+        put '/request_body', MultiJson.encode(user: 'Bobby T.'), {'CONTENT_TYPE' => 'application/json'}
+        last_response.body.should == 'Bobby T.'
+      end
+
+      it 'should convert XML bodies to params' do
+        post '/request_body', '<user>Bobby T.</user>', {'CONTENT_TYPE' => 'application/xml'}
+        last_response.body.should == 'Bobby T.'
+      end
+
+      it 'should convert XML bodies to params' do
+        put '/request_body', '<user>Bobby T.</user>', {'CONTENT_TYPE' => 'application/xml'}
+        last_response.body.should == 'Bobby T.'
+      end
 
+      it 'does not include parameters not defined by the body' do
+        subject.post '/omitted_params' do
+          body_params[:version].should == nil
+        end
+        post '/omitted_params', MultiJson.encode(user: 'Blah'), {'CONTENT_TYPE' => 'application/json'}
       end
     end
   end

spec/grape/middleware/versioner/param_spec.rb

@@ -0,0 +1,58 @@
+require 'spec_helper'
+
+describe Grape::Middleware::Versioner::Param do
+
+  let(:app) { lambda{|env| [200, env, env['api.version']]} }
+  subject { Grape::Middleware::Versioner::Param.new(app, @options || {}) }
+
+  it 'should set the API version based on the default param (apiver)' do
+    env = Rack::MockRequest.env_for("/awesome", {:params => {"apiver" => "v1"}})
+    subject.call(env)[1]["api.version"].should == 'v1'
+  end
+
+  it 'should cut (only) the version out of the params', :focus => true do
+    env = Rack::MockRequest.env_for("/awesome", {:params => {"apiver" => "v1", "other_param" => "5"}})
+    subject.call(env)[1]['rack.request.query_hash']["apiver"].should be_nil
+    subject.call(env)[1]['rack.request.query_hash']["other_param"].should == "5"
+  end
+
+  it 'should provide a nil version if no version is given' do
+    env = Rack::MockRequest.env_for("/")
+    subject.call(env).last.should be_nil
+  end
+
+  context 'with specified parameter name' do
+    before{ @options = {:parameter => ['v']}}
+    it 'should set the API version based on the custom parameter name' do
+      env = Rack::MockRequest.env_for("/awesome", {:params => {"v" => "v1"}})
+      s = subject.call(env)[1]["api.version"] == "v1"
+    end
+    it 'should not set the API version based on the default param' do
+      env = Rack::MockRequest.env_for("/awesome", {:params => {"apiver" => "v1"}})
+      s = subject.call(env)[1]["api.version"] == nil
+    end
+  end
+
+  context 'with specified versions' do
+    before{ @options = {:versions => ['v1', 'v2']}}
+    it 'should throw an error if a non-allowed version is specified' do
+      env = Rack::MockRequest.env_for("/awesome", {:params => {"apiver" => "v3"}})
+      catch(:error){subject.call(env)}[:status].should == 404
+    end
+
+    it 'should allow versions that have been specified' do
+      env = Rack::MockRequest.env_for("/awesome", {:params => {"apiver" => "v1"}})
+      subject.call(env)[1]["api.version"].should == 'v1'
+    end
+  end
+
+  it 'should return a 200 when no version is set (matches the first version found)' do
+    @options = {
+      :versions => ['v1'],
+      :version_options => {:using => :header}
+    }
+    env = Rack::MockRequest.env_for("/awesome", {:params => {}})
+    subject.call(env).first.should == 200
+  end
+
+end

spec/grape/middleware/versioner_spec.rb

@@ -9,4 +9,8 @@
   it 'should recognize :header' do
     klass.using(:header).should == Grape::Middleware::Versioner::Header
   end
+
+  it 'should recognize :param' do
+    klass.using(:param).should == Grape::Middleware::Versioner::Param
+  end
 end