Merge branch 'header_versioning'

Author: Michael Bleigh

Guardfile

@@ -4,6 +4,7 @@
 guard 'rspec', :version => 2 do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch(%r{^spec/support/shared_versioning_examples.rb$}) { |m| "spec/" }
   watch('spec/spec_helper.rb')  { "spec/" }
 end
 

README.markdown

@@ -15,7 +15,7 @@ Grape APIs are Rack applications that are created by subclassing `Grape::API`. B
 
 ```ruby
 class Twitter::API < Grape::API
-  version '1'
+  version 'v1', :using => :header, :vendor => 'twitter', :format => :json
 
   helpers do
     def current_user
@@ -68,10 +68,18 @@ run Twitter::API
 
 And would respond to the following routes:
 
-    GET  /1/statuses/public_timeline(.json)
-    GET  /1/statuses/home_timeline(.json)
-    GET  /1/statuses/show/:id(.json)
-    POST /1/statuses/update(.json)
+    GET  /statuses/public_timeline(.json)
+    GET  /statuses/home_timeline(.json)
+    GET  /statuses/show/:id(.json)
+    POST /statuses/update(.json)
+
+Versioning is handled with HTTP Accept head by default, but can be configures
+to [use different
+strategies](https://github.com/intridea/grape/wiki/API-Versioning). For
+example, to request the above with a version, you would make the following
+request:
+
+    curl -H Accept=application/vnd.twitter-v1+json http://localhost:9292/statuses/public_timeline
 
 Serialization takes place automatically. For more detailed usage information, please visit the [Grape Wiki](http://github.com/intridea/grape/wiki).
 

lib/grape.rb

@@ -21,6 +21,11 @@ module Auth
       autoload :Basic,  'grape/middleware/auth/basic'
       autoload :Digest,	'grape/middleware/auth/digest'
     end
+
+    module Versioner
+      autoload :Path,   'grape/middleware/versioner/path'
+      autoload :Header, 'grape/middleware/versioner/header'
+    end
   end
 
   module Util

lib/grape/api.rb

@@ -72,12 +72,16 @@ def prefix(prefix = nil)
       #     end
       #   end
       #
-      def version(*new_versions, &block)
-        if new_versions.any?
-          @versions = versions | new_versions
-          nest(block) { set(:version, new_versions) }
-        else
-          settings[:version]
+      def version(*args, &block)
+        if args.any?
+          options = args.pop if args.last.is_a? Hash
+          options ||= {}
+          options = {:using => :header}.merge!(options)
+          @versions = versions | args
+          nest(block) do
+            set(:version, args)
+            set(:version_options, options)
+          end
         end
       end
 
@@ -248,15 +252,15 @@ def route(methods, paths = ['/'], route_options = {}, &block)
             request_method = (method.to_s.upcase unless method == :any)
 
             routes << Route.new(route_options.merge({
-              :prefix => prefix, 
-              :version => version ? version.join('|') : nil, 
-              :namespace => namespace, 
-              :method => request_method, 
+              :prefix => prefix,
+              :version => settings[:version] ? settings[:version].join('|') : nil,
+              :namespace => namespace,
+              :method => request_method,
               :path => prepared_path,
               :params => path_params}))
 
-            route_set.add_route(endpoint, 
-              :path_info => path, 
+            route_set.add_route(endpoint,
+              :path_info => path,
               :request_method => request_method
             )
           end
@@ -357,10 +361,18 @@ def build_endpoint(&block)
           :format => settings[:error_format] || :txt, 
           :rescue_options => settings[:rescue_options],
           :rescue_handlers => settings[:rescue_handlers] || {}
-        b.use Rack::Auth::Basic, settings[:auth][:realm], &settings[:auth][:proc] if settings[:auth] && settings[:auth][:type] == :http_basic	
+
+        b.use Rack::Auth::Basic, settings[:auth][:realm], &settings[:auth][:proc] if settings[:auth] && settings[:auth][:type] == :http_basic
         b.use Rack::Auth::Digest::MD5, settings[:auth][:realm], settings[:auth][:opaque], &settings[:auth][:proc] if settings[:auth] && settings[:auth][:type] == :http_digest
-        b.use Grape::Middleware::Prefixer, :prefix => prefix if prefix        
-        b.use Grape::Middleware::Versioner, :versions => (version if version.is_a?(Array)) if version
+        b.use Grape::Middleware::Prefixer, :prefix => prefix if prefix
+
+        if settings[:version]
+          b.use Grape::Middleware::Versioner.using(settings[:version_options][:using]), {
+            :versions        => settings[:version],
+            :version_options => settings[:version_options]
+          }
+        end
+
         b.use Grape::Middleware::Formatter, :default_format => default_format || :json
         middleware.each{|m| b.use *m }
 
@@ -375,7 +387,6 @@ def build_endpoint(&block)
         }, &block)
         endpoint.send :include, helpers
         b.run endpoint
-        
         b.to_app
       end
 
@@ -396,7 +407,7 @@ def route_set
       def prepare_path(path)
         parts = []
         parts << prefix if prefix
-        parts << ':version' if version
+        parts << ':version' if settings[:version] && settings[:version_options][:using] == :path
         parts << namespace.to_s if namespace
         parts << path.to_s if path && '/' != path
         parts.last << '(.:format)'
@@ -405,12 +416,12 @@ def prepare_path(path)
 
       def compile_path(path, anchor = true)
         endpoint_options = {}
-        endpoint_options[:version] = /#{version.join('|')}/ if version
+        endpoint_options[:version] = /#{settings[:version].join('|')}/ if settings[:version]
 
         Rack::Mount::Strexp.compile(prepare_path(path), endpoint_options, %w( / . ? ), anchor)
       end
-    end  
-    
-    reset! 
+    end
+
+    reset!
   end
 end

lib/grape/middleware/versioner.rb

@@ -1,25 +1,25 @@
-require 'grape/middleware/base'
-
+# Versioners set env['api.version'] when a version is defined on an API and
+# on the requests. The current methods for determining version are:
+#
+#   :header - version from HTTP Accept header.
+#   :path   - version from uri. e.g. /v1/resource
+#
+# See individual classes for details.
 module Grape
   module Middleware
-    class Versioner < Base
-      def default_options
-        {
-          :pattern => /.*/i
-        }
-      end
-      
-      def before
-        pieces = env['PATH_INFO'].split('/')
-        potential_version = pieces[1]
-        if potential_version =~ options[:pattern]
-          if options[:versions] && !options[:versions].include?(potential_version)
-            throw :error, :status => 404, :message => "404 API Version Not Found"
-          end
-          
-          truncated_path = "/#{pieces[2..-1].join('/')}"
-          env['api.version'] = potential_version
-          env['PATH_INFO'] = truncated_path
+    module Versioner
+      extend self
+
+      # @param strategy [Symbol] :path or :header
+      # @return a middleware class based on strategy
+      def using(strategy)
+        case strategy
+        when :path
+          Path
+        when :header
+          Header
+        else
+          raise ArgumentError.new("Unknown :using for versioner: #{strategy}")
         end
       end
     end

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

lib/grape/middleware/versioner/path.rb

@@ -0,0 +1,42 @@
+require 'grape/middleware/base'
+
+module Grape
+  module Middleware
+    module Versioner
+      # This middleware sets various version related rack environment variables
+      # based on the uri path and removes the version substring from the uri
+      # path. If the version substring does not match any potential initialized
+      # versions, a 404 error is thrown.
+      # 
+      # Example: For a uri path
+      #   /v1/resource
+      # 
+      # The following rack env variables are set and path is rewritten to
+      # '/resource':
+      # 
+      #   env['api.version'] => 'v1'
+      # 
+      class Path < Base
+        def default_options
+          {
+            :pattern => /.*/i
+          }
+        end
+
+        def before
+          pieces = env['PATH_INFO'].split('/')
+          potential_version = pieces[1]
+          if potential_version =~ options[:pattern]
+            if options[:versions] && !options[:versions].include?(potential_version)
+              throw :error, :status => 404, :message => "404 API Version Not Found"
+            end
+
+            truncated_path = "/#{pieces[2..-1].join('/')}"
+            env['api.version'] = potential_version
+            env['PATH_INFO'] = truncated_path
+          end
+        end
+      end
+    end
+  end
+end

lib/grape/route.rb

@@ -16,7 +16,7 @@ def method_missing(method_id, *arguments)
     end
 
     def to_s
-      "#{route_method} #{route_path}"
+      "Version: #{route_version} #{route_method} #{route_path}"
     end
 
   end

lib/grape/util/hash_stack.rb

@@ -82,6 +82,10 @@ def concat(hash_stack)
         @stack.concat hash_stack.stack
         self
       end
+
+      def to_s
+        @stack.to_s
+      end
     end
   end
 end