Grape::API versioning based on request parameter.

Added an API versioner which searches for a named parameter (default is
'apiver') to find the specified api version. The name of the parameter
can be changed via the 'parameter' option when specifying the version.

Include all the same specs as already existed for the other versioners.
Update README markdown to explain this new versioning strategy.

Author: Jack Casey

README.markdown

@@ -110,8 +110,10 @@ 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`.
+
+
+### Header
 
     version 'v1', :using => :header
 
@@ -124,6 +126,8 @@ 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.
 
+### Path
+
     version 'v1', :using => :path
 
 Using this versioning strategy, clients should pass the desired version in the URL.
@@ -132,6 +136,20 @@ Using this versioning strategy, clients should pass the desired version in the U
 
 Serialization takes place automatically. 
 
+### Param
+
+    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.
+
+    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, 

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/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/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

spec/support/versioned_helpers.rb

@@ -6,6 +6,8 @@ def versioned_path(options = {})
   case options[:using]
   when :path
     File.join('/', options[:prefix] || '', options[:version], options[:path])
+  when :param
+    File.join('/', options[:prefix] || '', options[:path])
   when :header
     File.join('/', options[:prefix] || '', options[:path])
   else
@@ -17,6 +19,8 @@ def versioned_headers(options)
   case options[:using]
   when :path
     {}  # no-op
+  when :param
+    {}  # no-op
   when :header
     {
       'HTTP_ACCEPT' => "application/vnd.#{options[:vendor]}-#{options[:version]}+#{options[:format]}"
@@ -29,6 +33,10 @@ def versioned_headers(options)
 def versioned_get(path, version_name, version_options = {})
   path    = versioned_path(version_options.merge(:version => version_name, :path => path))
   headers = versioned_headers(version_options.merge(:version => version_name))
-  get path, {}, headers
+  params = {}
+  if version_options[:using] == :param
+    params = { version_options[:parameter] => version_name } 
+  end
+  get path, params, headers
 end