Merge pull request ruby-grape#175 from agworld/feature/parameter_versioning

Grape::API versioning based on request parameter.

Author: dblock

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