Add .scope to API to allow for scoping without modifying the URL.

Author: Michael Bleigh

lib/grape/api.rb

@@ -3,9 +3,10 @@
 require 'logger'
 
 module Grape
+  # The API class is the primary entry point for
+  # creating Grape APIs. Users should subclass this
+  # class in order to build an API.
   class API
-    module Helpers; end
-    
     class << self
       attr_reader :route_set
 
@@ -147,27 +148,34 @@ def namespace(space = nil, &block)
         end
       end
 
+      alias_method :group, :namespace
+      alias_method :resource, :namespace
+      alias_method :resources, :namespace
+      
+      # Create a scope without affecting the URL.
+      # 
+      # @param name [Symbol] Purely placebo, just allows to to name the scope to make the code more readable.
+      def scope(name = nil, &block)
+        nest(block)
+      end
+      
+      protected
+      
       # Execute first the provided block, then each of the
       # block passed in. Allows for simple 'before' setups
       # of settings stack pushes.
       def nest(*blocks, &block)
         blocks.reject!{|b| b.nil?}
         if blocks.any?
           settings_stack << {}
-          instance_eval &block
+          instance_eval &block if block_given?
           blocks.each{|b| instance_eval &b}
           settings_stack.pop
         else
           instance_eval &block
         end
       end
 
-      alias_method :group, :namespace
-      alias_method :resource, :namespace
-      alias_method :resources, :namespace
-      
-      protected
-      
       def build_endpoint(&block)
         b = Rack::Builder.new
         b.use Grape::Middleware::Error

lib/grape/endpoint.rb

@@ -25,6 +25,8 @@ def self.call(env)
 
     attr_reader :env, :request
 
+    # The parameters passed into the request as
+    # well as parsed from URL segments.
     def params
       @params ||= request.params.merge(env['rack.routing_args'] || {}).inject({}) do |h,(k,v)|
         h[k.to_s] = v
@@ -33,13 +35,21 @@ def params
       end
     end
 
+    # The API version as specified in the URL.
     def version; env['api.version'] end
 
+    # End the request and display an error to the
+    # end user with the specified message.
+    #
+    # @param message [String] The message to display.
+    # @param status [Integer] the HTTP Status Code. Defaults to 403.
     def error!(message, status=403)
       throw :error, :message => message, :status => status
     end
 
     # Set or retrieve the HTTP status code.
+    #
+    # @param status [Integer] The HTTP Status Code to return for this request.
     def status(status = nil)
       if status
         @status = status

spec/grape/api_spec.rb

@@ -313,4 +313,31 @@ def two
       lambda{get '/howdy'}.should_not raise_error
     end
   end
+  
+  describe '.scope' do
+    it 'should scope the various settings' do
+      subject.version 'v2'
+      
+      subject.scope :legacy do
+        version 'v1'
+        
+        get '/abc' do
+          version
+        end
+      end
+      
+      subject.get '/def' do
+        version
+      end
+      
+      get '/v2/abc'
+      last_response.status.should == 404
+      get '/v1/abc'
+      last_response.status.should == 200
+      get '/v1/def'
+      last_response.status.should == 404
+      get '/v2/def'
+      last_response.status.should == 200
+    end
+  end
 end