Refactored api structure madness into api route collection.

Author: dblock

README.markdown

@@ -83,20 +83,17 @@ you simply use the `rescue_from` method inside your API declaration:
       rescue_from ArgumentError, NotImplementedError # :all for all errors
     end
 
-## API Structure
+## Inspecting an API
 
-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. 
+Grape exposes arrays of API versions and compiled routes. Each route contains a prefix, version, namespace, method and path.
 
     class TwitterAPI < Grape::API      
 
       version 'v1'
       get "version" do 
         api.version
       end
-      
+
       version 'v2'
       namespace "ns" do
         get "version" do
@@ -106,22 +103,15 @@ path. The structure is retrieved via the `structure` method.
 
     end
 
-Yields the following `TwitterAPI::structure`.
-
-    {
-      "v1" => [ 
-        { :method=>"GET", :path=>"version(.:format)"} ], 
-      "v2"=> {
-        "ns"=>[ { :method=>"GET", :path=>"version(.:format)" }]
-       }
-    }
+    TwitterAPI::versions # yields [ 'v1', 'v2' ]
+    TwitterAPI::routes # yields an array of Grape::Route objects
 
 ## Note on Patches/Pull Requests
 
 * Fork the project.
 * Make your feature addition or bug fix.
 * Add tests for it. This is important so I don't break it in a future version unintentionally.
-* Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Commit, do not mess with Rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
 * Send me a pull request. Bonus points for topic branches.
 
 ## Copyright

lib/grape.rb

@@ -6,6 +6,7 @@ module Grape
   autoload :Endpoint, 'grape/endpoint'
   autoload :MiddlewareStack, 'grape/middleware_stack'
   autoload :Client, 'grape/client'
+  autoload :Route, 'grape/route'
 
   module Middleware
     autoload :Base,      'grape/middleware/base'

lib/grape/api.rb

@@ -10,7 +10,8 @@ module Grape
   class API
     class << self
       attr_reader :route_set
-      attr_reader :structure
+      attr_reader :versions
+      attr_reader :routes
 
       def logger
         @logger ||= Logger.new($STDOUT)
@@ -71,7 +72,12 @@ def prefix(prefix = nil)
       #   end
       #
       def version(*new_versions, &block)
-        new_versions.any? ? nest(block){ set(:version, new_versions) } : settings[:version]
+        if new_versions.any?
+          @versions = versions | new_versions
+          nest(block) { set(:version, new_versions) }
+        else
+          settings[:version]
+        end
       end
 
       # Specify the default format for the API's 
@@ -180,52 +186,27 @@ def route(methods, paths, &block)
         methods = Array(methods)
         paths = ['/'] if paths == []
         paths = Array(paths)
-        endpoint = build_endpoint(&block)
+        endpoint = build_endpoint(&block)        
         options = {}
+        
         options[:version] = /#{version.join('|')}/ if version
 
         methods.each do |method|
           paths.each do |path|
-            path = Rack::Mount::Strexp.compile(compile_path(path), options, %w( / . ? ), true)
+            compiled_path = compile_path(path)
+            path = Rack::Mount::Strexp.compile(compiled_path, options, %w( / . ? ), true)
+            request_method = (method.to_s.upcase unless method == :any)
+            routes << Route.new(prefix, 
+              version ? version.join('|') : nil, 
+              namespace, 
+              request_method, 
+              compiled_path)
             route_set.add_route(endpoint, 
               :path_info => path, 
-              :request_method => (method.to_s.upcase unless method == :any)
+              :request_method => request_method
             )
           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
@@ -272,10 +253,13 @@ 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 ||= {}
+      # An array of API routes.
+      def routes
+        @routes ||= []
+      end
+      
+      def versions
+        @versions ||= []
       end
 
       protected
@@ -305,7 +289,7 @@ def build_endpoint(&block)
           :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 Grape::Middleware::Prefixer, :prefix => prefix if prefix        
+        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
         middleware.each{|m| b.use *m }

lib/grape/route.rb

@@ -0,0 +1,25 @@
+module Grape
+
+  # A compiled route for inspection.
+  class Route
+  
+    attr_reader :prefix
+    attr_reader :version
+    attr_reader :namespace
+    attr_reader :method
+    attr_reader :path
+    
+    def initialize(prefix, version, namespace, method, path)
+      @prefix = prefix
+      @version = version
+      @namespace = namespace
+      @method = method
+      @path = path
+    end
+    
+    def to_s
+      "#{method} #{path}"
+    end
+    
+  end
+end

spec/grape/api_spec.rb

@@ -618,94 +618,63 @@ def two
     end
   end
 
-  describe "simple version structure" do
-    before(:each) do
-      subject.get :hello do
-        "No version"
+  context "routes" do
+    describe "empty api structure" do
+      it "returns an empty array of routes" do
+        subject.routes.should == []
+      end
+    end     
+    describe "single method api structure" do
+      before(:each) do
+        subject.get :ping do 
+          'pong'
+        end
       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
+      it "returns one route" do
+        subject.routes.size.should == 1
+        route = subject.routes[0]
+        route.version.should be_nil
+        route.path.should == "/ping(.:format)"
+        route.method.should == "GET"
+      end
+    end    
+    describe "api structure with two versions and a namespace" do
+      class TwitterAPI < Grape::API
+        # version v1
+        version 'v1'
+        get "version" do 
           api.version
         end
+        # version v2
+        version 'v2'
+        prefix 'p'
+        namespace "n1" do
+          namespace "n2" do
+            get "version" do
+              api.version
+            end
+          end
+        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']}"
+      it "should return versions" do
+        TwitterAPI::versions.should == [ 'v1', 'v2' ]
       end
-      subject.version 'v2'
-      subject.get :hello do
-        "Version: #{request.env['api.version']} w/o namespace"
+      it "should set route paths" do
+        TwitterAPI::routes.size.should == 2
+        TwitterAPI::routes[0].path.should == "/:version/version(.:format)"
+        TwitterAPI::routes[1].path.should == "/p/:version/n1/n2/version(.:format)"
       end
-      subject.namespace :ns1 do
-        get :hello do
-          "Version: #{request.env['api.version']}"
-        end
+      it "should set route versions" do
+        TwitterAPI::routes[0].version.should == 'v1'
+        TwitterAPI::routes[1].version.should == 'v2'
       end
-      subject.namespace :ns2 do
-        get :hello do
-          "Version: #{request.env['api.version']}"
-        end
+      it "should set a nested namespace" do
+        TwitterAPI::routes[1].namespace.should == "/n1/n2"
       end
-      subject.post :goodbye do
-        "Version: #{request.env['api.version']} w/o namespace"
+      it "should set prefix" do
+        TwitterAPI::routes[1].prefix.should == 'p'
       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