accept header based versioning middleware

Author: Jerry Cheung

lib/grape/middleware/versioner/header.rb

@@ -0,0 +1,45 @@
+require 'grape/middleware/base'
+
+module Grape
+  module Middleware
+    module Versioner
+      # This middleware sets various version related rack environment variables
+      # based on the HTTP Accept header with the pattern:
+      # application/vnd.:vendor-:version+:format
+      #
+      # Example: For request header
+      #    Accept: application/vnd.mycompany-v1+json
+      #
+      # The following rack env variables are set:
+      #
+      #    env['api.type']    => 'application'
+      #    env['api.subtype'] => 'vnd.mycompany-v1+json'
+      #    env['api.vendor]   => 'mycompany'
+      #    env['api.version]  => 'v1'
+      #    env['api.format]   => 'format'
+      #
+      # If version does not match this route, then a 404 is throw with
+      # X-Cascade header to alert Rack::Mount to attempt the next matched
+      # route.
+      class Header < Base
+        def before
+          accept = env['HTTP_ACCEPT'] || ""
+          accept.strip.scan(/^(.+?)\/(.+?)$/) do |type, subtype|
+            env['api.type']    = type
+            env['api.subtype'] = subtype
+
+            subtype.scan(/vnd\.(.+)?-(.+)?\+(.*)?/) do |vendor, version, format|
+              if options[:versions] && !options[:versions].include?(version)
+                throw :error, :status => 404, :headers => {'X-Cascade' => 'pass'}, :message => "404 API Version Not Found"
+              end
+
+              env['api.version'] = version
+              env['api.vendor']  = vendor
+              env['api.format']  = format  # weird that Grape::Middleware::Formatter also does this
+            end
+          end
+        end
+      end
+    end
+  end
+end

spec/grape/middleware/versioner/header_spec.rb

@@ -0,0 +1,67 @@
+require 'spec_helper'
+
+describe Grape::Middleware::Versioner::Header do
+  let(:app) { lambda{|env| [200, env, env]} }
+  let(:accept) { 'application/vnd.vendor-v1+json' }
+  subject { Grape::Middleware::Versioner::Header.new(app, @options || {}) }
+
+  context 'api.type and api.subtype' do
+    it 'should set any type and any subtype' do
+      env = subject.call('HTTP_ACCEPT' => '*/*').last
+      env['api.type'].should eql '*'
+      env['api.subtype'].should eql '*'
+    end
+
+    it 'should set preferred type and subtype' do
+      env = subject.call('HTTP_ACCEPT' => 'text/html').last
+      env['api.type'].should eql 'text'
+      env['api.subtype'].should eql 'html'
+    end
+  end
+
+  context 'api.format' do
+    it 'should be set' do
+      env = subject.call('HTTP_ACCEPT' => accept).last
+      env['api.format'].should eql 'json'
+    end
+
+    it 'should be nil if not provided' do
+      env = subject.call('HTTP_ACCEPT' => 'application/vnd.vendor-v1').last
+      env['api.format'].should eql nil
+    end
+  end
+
+  context 'matched version' do
+    before do
+      @options = {
+        :versions => ['v1'],
+        :version_options => {:using => :header}
+      }
+    end
+
+    it 'should set api.vendor' do
+      env = subject.call('HTTP_ACCEPT' => accept).last
+      env['api.vendor'].should eql 'vendor'
+    end
+
+    it 'should set api.version' do
+      env = subject.call('HTTP_ACCEPT' => accept).last
+      env['api.version'].should eql 'v1'
+    end
+  end
+
+  context 'no matched version' do
+    before do
+      @options = {
+        :versions => ['unknown_version'],
+        :version_options => {:using => :header}
+      }
+    end
+
+    it 'should throw 404 error with X-Cascade header set to pass' do
+      expect {
+        env = subject.call('HTTP_ACCEPT' => accept).last
+      }.to throw_symbol(:error, :status => 404, :headers => {'X-Cascade' => 'pass'}, :message => "404 API Version Not Found")
+    end
+  end
+end