Initial cut for structure layout.

Author: dblock

README.markdown

@@ -83,6 +83,39 @@ you simply use the `rescue_from` method inside your API declaration:
       rescue_from ArgumentError, NotImplementedError # :all for all errors
     end
 
+## API Structure
+
+Grape exposes the API structure as a hash. The hash keys are API versions (`:default` when version is omitted). When namespaces are present,
+each value is a hash of namespaces with paths as values. When namespaces are not present, each value is an array of paths. Each path is a hash
+containing two keys, `:method` which holds a string containing the path's HTTP request type, and `:path` which holds a string representing the
+path. The structure is retrieved via the `structure` method. 
+
+    class TwitterAPI < Grape::API      
+
+      version 'v1'
+      get "version" do 
+        api.version
+      end
+      
+      version 'v2'
+      namespace "ns" do
+        get "version" do
+          api.version
+        end
+      end      
+
+    end
+
+Yields the following `TwitterAPI::structure`.
+
+    {
+      "v1" => [ 
+        { :method=>"GET", :path=>"version(.:format)"} ], 
+      "v2"=> {
+        "ns"=>[ { :method=>"GET", :path=>"version(.:format)" }]
+       }
+    }
+
 ## Note on Patches/Pull Requests
 
 * Fork the project.

lib/grape/api.rb

@@ -10,6 +10,7 @@ module Grape
   class API
     class << self
       attr_reader :route_set
+      attr_reader :structure
 
       def logger
         @logger ||= Logger.new($STDOUT)
@@ -159,7 +160,7 @@ def http_basic(options = {}, &block)
 
       def http_digest(options = {}, &block)
         options[:realm] ||= "API Authorization"
-	options[:opaque] ||= "secret"
+        options[:opaque] ||= "secret"
         auth :http_digest, options, &block
       end
 
@@ -192,6 +193,39 @@ def route(methods, paths, &block)
             )
           end
         end
+ 
+        # create API structure
+        (version || [ :default ]).each { |v|
+          
+          ms = []
+          methods.each { |m|
+            paths.each { |p|
+              ms << {
+                :method => m,
+                :path => p.to_s
+              }
+            }
+          }
+          
+          if namespace == '/'
+            if structure[v].is_a?(Hash)
+              structure[v][:default] ||= (structure[v][:default] || {}).merge(structure[v])
+              if (structure[v][:default].is_a?(Hash))
+                structure[v][:default] = [ structure[v][:default], ms ]
+              else
+                structure[v][:default] |= ms
+              end
+            else
+              structure[v] ||= []
+              structure[v] |= ms
+            end
+          else
+            structure[v] = { :default => structure[v] } if structure[v].is_a?(Array)
+            structure[v] ||= {}
+            structure[v][namespace[1..namespace.length - 1].to_s] = ms
+          end          
+        }
+        
       end
 
       def get(*paths, &block); route('GET', paths, &block) end
@@ -238,6 +272,12 @@ def middleware
         settings_stack.inject([]){|a,s| a += s[:middleware] if s[:middleware]; a}
       end
 
+      # API structure contains a hash of API versions to API methods.
+      # If the API is not versioned, the hash contains a single :current key.
+      def structure
+        @structure ||= {}
+      end
+      
       protected
 
       # Execute first the provided block, then each of the
@@ -264,7 +304,7 @@ def build_endpoint(&block)
           :format => settings[:error_format] || :txt, 
           :rescue_options => settings[:rescue_options]
         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 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::Formatter, :default_format => default_format || :json
@@ -284,7 +324,7 @@ def inherited(subclass)
       def route_set
         @route_set ||= Rack::Mount::RouteSet.new
       end
-      
+
       def compile_path(path)
         parts = []
         parts << prefix if prefix

spec/grape/api_spec.rb

@@ -617,4 +617,95 @@ def two
       last_response.status.should eql 403
     end
   end
+
+  describe "simple version structure" do
+    before(:each) do
+      subject.get :hello do
+        "No version"
+      end
+    end
+    it "versions api" do      
+      get '/hello'
+      last_response.body.should eql "No version"      
+    end
+    it "returns an array of versions" do
+      subject.structure.should == 
+      {
+        :default => [ { :method => "GET", :path => "hello" } ],
+      }
+    end
+  end
+  
+  describe "twitter versions" do
+    class TwitterAPI < Grape::API
+      version 'v1'
+      get "version" do 
+        api.version
+      end
+      version 'v2'
+      namespace "ns" do
+        get "version" do
+          api.version
+        end
+      end
+    end
+    it "should return a single structure with both versions" do
+      TwitterAPI::structure.should == {
+        "v1"=>[{:method=>"GET", :path=>"version(.:format)"}], 
+        "v2"=>{
+          "ns"=>[{:method=>"GET", :path=>"version(.:format)"}]
+        }}
+    end
+  end
+  
+  describe "nested versions" do
+    before(:each) do
+      subject.get :hello do
+        "No version"
+      end
+      subject.version 'v1'
+      subject.get :hello do
+        "Version: #{request.env['api.version']}"
+      end
+      subject.version 'v2'
+      subject.get :hello do
+        "Version: #{request.env['api.version']} w/o namespace"
+      end
+      subject.namespace :ns1 do
+        get :hello do
+          "Version: #{request.env['api.version']}"
+        end
+      end
+      subject.namespace :ns2 do
+        get :hello do
+          "Version: #{request.env['api.version']}"
+        end
+      end
+      subject.post :goodbye do
+        "Version: #{request.env['api.version']} w/o namespace"
+      end
+    end
+    it "versions api" do      
+      get '/hello'
+      last_response.body.should eql "No version"      
+      get '/v1/hello'
+      last_response.body.should eql "Version: v1"      
+      get '/v2/ns1/hello'
+      last_response.body.should eql "Version: v2"      
+      get '/v2/ns2/hello'
+      last_response.body.should eql "Version: v2"      
+    end
+    it "returns an array of versions" do
+      subject.structure.should == 
+      {
+        :default => [ { :method => "GET", :path => "hello" } ],
+        "v1" => [ { :method => "GET", :path => "hello" } ],
+        "v2" => {
+          :default => [ { :method => "GET", :path => "hello" }, { :method => "POST", :path => "goodbye" } ],
+          "ns1" => [ { :method => "GET", :path => "hello" } ],
+          "ns2" => [ { :method => "GET", :path => "hello" } ]
+        } 
+      }
+    end
+  end
 end