rack-api 0.1.0 → 0.1.1

data/.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 pkg
 tmp
+docs

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    rack-api (0.1.0)
+    rack-api (0.1.1)
       activesupport (~> 3.0.6)
       rack (~> 1.2.1)
       rack-mount (~> 0.6.14)

data/README.rdoc

@@ -24,8 +24,106 @@ Create web app APIs that respond to one or more formats using an elegant DSL.
     end
   end
 
+=== Rails Integration
+
+First, set up your Gemfile like this:
+
+  gem "rack-api", "~> 0.1.0", :require => "rack/api"
+
+Create your API somewhere. In this example, we'll add it to <tt>lib/api.rb</tt>.
+
+  Rack::API.app do
+    prefix "api"
+
+    version :v1 do
+      get "status(.:format)" do
+        {:success => true, :time => Time.now}
+      end
+    end
+  end
+
+Load this file somehow. I'd create a <tt>config/initializers/dependencies.rb</tt> with something like
+
+  require "lib/api"
+
+Finally, you can set up the API routing. Open <tt>config/routes.rb</tt> and add the following line:
+
+  mount Rack::API => "/"
+
+If you define your API by inheriting from the Rack::API class, remember to mount your class instead.
+
+  mount MyAPI => "/"
+
 For additional examples, see https://github.com/fnando/rack-api/tree/master/examples.
 
+=== Using RSpec with Rack::API
+
+You can easily test Rack::API apps by using Rack::Test. This applies to both RSpec and Test Unit. See what you need to do if you want to use it with RSpec.
+
+First, open your <tt>spec/spec_helper.rb</tt> and add something like this:
+
+  require "rspec"
+  require "rack/test"
+
+  RSpec.configure do |config|
+    config.include Rack::Test::Methods
+  end
+
+Then you can go to your spec file, say, <tt>spec/api_spec.rb</tt>. You need to define a helper method called +app+, which will point to your Rack::API (the class itself or your own class).
+
+  require "spec_helper"
+
+  describe Rack::API do
+    # Remember to use your own class if you
+    # inherited from Rack::API
+    def app; Rack::API; end
+
+    it "renders status page" do
+      get "/api/v1/status"
+      JSON.load(last_response.body).should == {:status => "running"}
+      last_response.status.should == 200
+    end
+  end
+
+If you want to do expectations over basic authentication, you'll have some like this:
+
+  require "spec_helper"
+
+  describe Rack::API do
+    def basic_auth(username, password)
+      "Basic " + Base64.encode64("#{username}:#{password}")
+    end
+
+    it "requires authentication" do
+      get "/api/v1/status"
+      last_response.status.should == 401
+    end
+
+    it "grants access" do
+      get "/api/v1/status", {"HTTP_AUTHORIZATION" => basic_auth("john", "test")}
+      last_response.status.should == 200
+    end
+  end
+
+To reduce duplication, you can move both <tt>basic_auth</tt> and <tt>app</tt> methods to a module, which will be included on RSpec.
+
+  RSpec.configure do |config|
+    config.include Rack::Test::Methods
+    config.include Helpers
+  end
+
+Your <tt>Helpers</tt> module may look like this:
+
+  module Helpers
+    def app
+      Rack::API
+    end
+
+    def basic_auth(username, password)
+      "Basic " + Base64.encode64("#{username}:#{password}")
+    end
+  end
+
 == Maintainer
 
 * Nando Vieira (http://nandovieira.com.br)

data/Rakefile

@@ -3,3 +3,10 @@ Bundler::GemHelper.install_tasks
 
 require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new
+
+require "rake/rdoctask"
+Rake::RDocTask.new do |t|
+  t.rdoc_dir = "docs"
+  t.main = "README.rdoc"
+  t.rdoc_files.include "README.rdoc", *Dir["lib/**/*.rb"]
+end

data/examples/custom_format.rb

@@ -0,0 +1,32 @@
+$:.push(File.dirname(__FILE__) + "/../lib")
+
+# Just run `ruby examples/formats.rb` and then use something like
+# `curl http://localhost:2345/api/v1/hello.xml`.
+
+require "rack/api"
+require "active_support/all"
+
+module Rack
+  class API
+    module Formatter
+      class Xml < Base
+        def to_format
+          object.to_xml(:root => :messages)
+        end
+      end
+    end
+  end
+end
+
+Rack::API.app do
+  prefix "api"
+  respond_to :xml
+
+  version :v1 do
+    get "/hello(.:format)" do
+      {:message => "Hello from Rack API"}
+    end
+  end
+end
+
+Rack::Handler::Thin.run Rack::API, :Port => 2345

data/examples/formats.rb

@@ -0,0 +1,19 @@
+$:.push(File.dirname(__FILE__) + "/../lib")
+
+# Just run `ruby examples/formats.rb` and then use something like
+# `curl http://localhost:2345/api/v1/hello.json` or
+# `curl http://localhost:2345/api/v1/hello.jsonp?callback=myJSHandler`.
+
+require "rack/api"
+
+Rack::API.app do
+  prefix "api"
+
+  version :v1 do
+    get "/hello(.:format)" do
+      {:message => "Hello from Rack API"}
+    end
+  end
+end
+
+Rack::Handler::Thin.run Rack::API, :Port => 2345

data/lib/rack/api.rb

@@ -3,15 +3,23 @@ require "rack/mount"
 require "active_support/hash_with_indifferent_access"
 require "json"
 require "logger"
+require "forwardable"
 
 module Rack
   class API
     autoload :App, "rack/api/app"
     autoload :Formatter, "rack/api/formatter"
+    autoload :Middleware, "rack/api/middleware"
     autoload :Runner, "rack/api/runner"
     autoload :Response, "rack/api/response"
     autoload :Version, "rack/api/version"
 
+    class << self
+      extend Forwardable
+
+      def_delegators :runner, :version, :use, :prefix, :basic_auth, :helper, :respond_to
+    end
+
     # A shortcut for defining new APIs. Instead of creating a
     # class that inherits from Rack::API, you can simply pass a
     # block to the Rack::API.app method.
@@ -25,41 +33,6 @@ module Rack
       runner
     end
 
-    # Add a middleware to the stack execution.
-    #
-    #   Rack::API.app do
-    #     use MyMiddleware
-    #   end
-    #
-    def self.use(m)
-      runner.use(m)
-    end
-
-    # Create a new API version.
-    #
-    #   Rack::API.app do
-    #     version "v1" do
-    #       # define your API
-    #     end
-    #   end
-    #
-    def self.version(name, &block)
-      runner.version(name, &block)
-    end
-
-    # Set an additional url prefix.
-    #
-    #   Rack::API.app do
-    #     prefix "api"
-    #     version("v1") {}
-    #   end
-    #
-    # This API will be available through <tt>/api/v1</tt> path.
-    #
-    def self.prefix(name)
-      runner.prefix(name)
-    end
-
     # Reset all API definitions while using the Rack::API.app method.
     #
     def self.reset!

data/lib/rack/api/app.rb

@@ -117,6 +117,15 @@ module Rack
         @headers = nil
       end
 
+      # Return credentials for Basic Authentication request.
+      #
+      def credentials
+        @credentials ||= begin
+          request = Rack::Auth::Basic::Request.new(env)
+          request.provided? ? request.credentials : []
+        end
+      end
+
       # Render the result of block.
       #
       def call(env) # :nodoc:

data/lib/rack/api/middleware.rb

@@ -0,0 +1,7 @@
+module Rack
+  class API
+    module Middleware
+      autoload :Format, "rack/api/middleware/format"
+    end
+  end
+end

data/lib/rack/api/middleware/format.rb

@@ -0,0 +1,23 @@
+module Rack
+  class API
+    module Middleware
+      class Format
+        def initialize(app, formats)
+          @app, @formats = app, formats.collect {|f| f.to_s}
+        end
+
+        def call(env)
+          request = Rack::Request.new(env)
+          params = request.env["rack.routing_args"].merge(request.params)
+          requested_format = params.fetch(:format, "json")
+
+          if @formats.include?(requested_format)
+            @app.call(env)
+          else
+            [406, {"Content-Type" => "text/plain"}, ["Invalid format"]]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rack/api/runner.rb

@@ -7,22 +7,76 @@ module Rack
 
       def initialize
         @settings = {
-          :prefix      => "/",
-          :formats     => %w[json jsonp],
-          :middlewares => []
+          :middlewares => [],
+          :helpers => [],
+          :global => {
+            :prefix      => "/",
+            :formats     => %w[json jsonp],
+            :middlewares => [],
+            :helpers     => []
+          }
         }
       end
 
+      # Set configuration based on scope. When defining values outside version block,
+      # will set configuration using <tt>settings[:global]</tt> namespace.
+      #
+      # Use the Rack::API::Runner#option method to access a given setting.
+      #
+      def set(name, value, mode = :override)
+        target = settings[:version] ? settings : settings[:global]
+
+        if mode == :override
+          target[name] = value
+        else
+          target[name] << value
+        end
+      end
+
+      # Try to fetch local configuration, defaulting to the global setting.
+      # Return +nil+ when no configuration is defined.
+      #
+      def option(name, mode = :any)
+        if mode == :merge && (settings[name].kind_of?(Array) || settings[:global][name].kind_of?(Array))
+          settings[:global].fetch(name, []) | settings.fetch(name, [])
+        else
+          settings.fetch(name, settings[:global][name])
+        end
+      end
+
       # Add a middleware to the execution stack.
       #
+      # Global middlewares will be merged with local middlewares.
+      #
+      #   Rack::API.app do
+      #     use ResponseTime
+      #
+      #     version :v1 do
+      #       use Gzip
+      #     end
+      #   end
+      #
+      # The middleware stack will be something like <tt>[ResponseTime, Gzip]</tt>.
+      #
       def use(middleware, *args)
-        settings[:middlewares] << [middleware, *args]
+        set :middlewares, [middleware, *args], :append
       end
 
       # Set an additional url prefix.
       #
       def prefix(name)
-        settings[:prefix] = name
+        set :prefix, name
+      end
+
+      # Add a helper to application.
+      #
+      #   helper MyHelpers
+      #   helper {  }
+      #
+      def helper(mod = nil, &block)
+        mod = Module.new(&block) if block_given?
+        raise ArgumentError, "you need to pass a module or block" unless mod
+        set :helpers, mod, :append
       end
 
       # Create a new API version.
@@ -48,8 +102,34 @@ module Rack
       #       User.authenticate(user, pass)
       #     end
       #   end
+      #
+      # You can disable basic authentication by providing <tt>:none</tt> as
+      # realm.
+      #
+      #   Rack::API.app do
+      #     basic_auth "Protected Area" do |user, pass|
+      #       User.authenticate(user, pass)
+      #     end
+      #
+      #     version :v1 do
+      #       # this version is protected by the
+      #       # global basic auth block above.
+      #     end
+      #
+      #     version :v2 do
+      #       basic_auth :none
+      #       # this version is now public
+      #     end
+      #
+      #     version :v3 do
+      #       basic_auth "Admin" do |user, pass|
+      #         user == "admin" && pass == "test"
+      #       end
+      #     end
+      #   end
+      #
       def basic_auth(realm = "Restricted Area", &block)
-        settings[:auth] = [realm, block]
+        set :auth, (realm == :none ? :none : [realm, block])
       end
 
       # Define the formats that this app implements.
@@ -65,8 +145,20 @@ module Rack
       # See Rack::API::Formatter::Jsonp for an example on how to create additional
       # formatters.
       #
+      # Local formats will override the global configuration on that context.
+      #
+      #   Rack::API.app do
+      #     respond_to :json, :xml, :jsonp
+      #
+      #     version :v1 do
+      #       respond_to :json
+      #     end
+      #   end
+      #
+      # The code above will accept only <tt>:json</tt> as format on version <tt>:v1</tt>.
+      #
       def respond_to(*formats)
-        settings[:formats] = formats
+        set :formats, formats
       end
 
       # Hold all routes.
@@ -102,15 +194,30 @@ module Rack
         RUBY
       end
 
+      private
       def mount_path(path) # :nodoc:
-        Rack::Mount::Utils.normalize_path([settings[:prefix], settings[:version], path].join("/"))
+        Rack::Mount::Utils.normalize_path([option(:prefix), settings[:version], path].join("/"))
       end
 
       def build_app(block) # :nodoc:
+        app = App.new(:block => block)
         builder = Rack::Builder.new
-        builder.use Rack::Auth::Basic, settings[:auth][0], &settings[:auth][1] if settings[:auth]
-        settings[:middlewares].each {|middleware| builder.use(*middleware)}
-        builder.run App.new(:block => block)
+
+        # Add middleware for basic authentication.
+        auth = option(:auth)
+        builder.use Rack::Auth::Basic, auth[0], &auth[1] if auth && auth != :none
+
+        # Add middleware for format validation.
+        builder.use Rack::API::Middleware::Format, option(:formats)
+
+        # Add middlewares to executation stack.
+        option(:middlewares, :merged).each {|middleware| builder.use(*middleware)}
+
+        # Apply helpers to app.
+        helpers = option(:helpers)
+        app.extend *helpers unless helpers.empty?
+
+        builder.run(app)
         builder.to_app
       end
     end

data/lib/rack/api/version.rb

@@ -3,7 +3,7 @@ module Rack
     module Version
       MAJOR = 0
       MINOR = 1
-      PATCH = 0
+      PATCH = 1
       STRING = "#{MAJOR}.#{MINOR}.#{PATCH}"
     end
   end

data/spec/rack-api/basic_auth_spec.rb

@@ -3,9 +3,23 @@ require "spec_helper"
 describe Rack::API, "Basic Authentication" do
    before do
     Rack::API.app do
+      basic_auth do |user, pass|
+        user == "admin" && pass == "test"
+      end
+
       version :v1 do
+        get("/") { {:success => true} }
+      end
+
+      version :v2 do
+        basic_auth :none
+        get("/") { {:success => true} }
+        get("/credentials") { credentials }
+      end
+
+      version :v3 do
         basic_auth do |user, pass|
-          user == "admin" && pass == "test"
+          user == "john" && pass == "test"
         end
 
         get("/") { {:success => true} }
@@ -13,18 +27,59 @@ describe Rack::API, "Basic Authentication" do
     end
   end
 
-  it "denies access" do
-    get "/v1/"
-    last_response.status.should == 401
+  context "global authorization" do
+    it "denies access" do
+      get "/v1/"
+      last_response.status.should == 401
+
+      get "/v1/", {}, "HTTP_AUTHORIZATION" => basic_auth("admin", "invalid")
+      last_response.status.should == 401
+
+      get "/v1/", {}, "HTTP_AUTHORIZATION" => basic_auth("john", "test")
+      last_response.status.should == 401
+    end
+
+    it "grants access" do
+      get "/v1/", {}, "HTTP_AUTHORIZATION" => basic_auth("admin", "test")
 
-    get "/v1/", {}, "HTTP_AUTHORIZATION" => basic_auth("admin", "invalid")
-    last_response.status.should == 401
+      last_response.status.should == 200
+      JSON.load(last_response.body).should == {"success" => true}
+    end
   end
 
-  it "grants access" do
-    get "/v1/", {}, "HTTP_AUTHORIZATION" => basic_auth("admin", "test")
+  context "no authorization" do
+    it "grants access" do
+      get "/v2/"
+
+      last_response.status.should == 200
+      JSON.load(last_response.body).should == {"success" => true}
+    end
+  end
+
+  context "local authorization" do
+    it "denies access" do
+      get "/v3/"
+      last_response.status.should == 401
+
+      get "/v3/", {}, "HTTP_AUTHORIZATION" => basic_auth("admin", "test")
+      last_response.status.should == 401
+    end
+
+    it "grants access" do
+      get "/v3/", {}, "HTTP_AUTHORIZATION" => basic_auth("john", "test")
+
+      last_response.status.should == 200
+      JSON.load(last_response.body).should == {"success" => true}
+    end
+  end
+
+  it "returns credentials" do
+    get "/v2/credentials", {}, "HTTP_AUTHORIZATION" => basic_auth("admin", "test")
+    JSON.load(last_response.body).should == ["admin", "test"]
+  end
 
-    last_response.status.should == 200
-    JSON.load(last_response.body).should == {"success" => true}
+  it "returns empty array when no credentials are provided" do
+    get "/v2/credentials"
+    JSON.load(last_response.body).should == []
   end
 end

data/spec/rack-api/format_spec.rb

@@ -11,7 +11,7 @@ describe Rack::API, "Format" do
     end
   end
 
-  it "ignores unknown formats" do
+  it "ignores unknown paths/formats" do
     get "/users.xml"
     last_response.status.should == 404
   end
@@ -26,6 +26,16 @@ describe Rack::API, "Format" do
     end
   end
 
+  context "invalid format" do
+    it "renders 406" do
+      get "/v1/users.invalid"
+
+      last_response.status.should == 406
+      last_response.body.should == "Invalid format"
+      last_response.headers["Content-Type"].should == "text/plain"
+    end
+  end
+
   context "JSONP" do
     it "renders when set through query string" do
       get "/v1", :format => "jsonp"

data/spec/rack-api/helpers_spec.rb

@@ -0,0 +1,33 @@
+require "spec_helper"
+
+describe Rack::API, "Helpers" do
+  before do
+    Rack::API.app do
+      version :v1 do
+        helper Module.new {
+          def helper_from_module
+            "module"
+          end
+        }
+
+        helper do
+          def helper_from_block
+            "block"
+          end
+        end
+
+        get("/") { [helper_from_block, helper_from_module] }
+      end
+    end
+  end
+
+  it "adds module helper" do
+    get "/v1"
+    JSON.load(last_response.body).should include("module")
+  end
+
+  it "adds block helper" do
+    get "/v1"
+    JSON.load(last_response.body).should include("block")
+  end
+end

data/spec/rack-api/runner_spec.rb

@@ -11,28 +11,23 @@ describe Rack::API::Runner do
 
   it "sets available formats" do
     subject.respond_to(:json, :jsonp, :atom)
-    subject.settings[:formats].should == [:json, :jsonp, :atom]
+    subject.option(:formats).should == [:json, :jsonp, :atom]
   end
 
   it "sets prefix option" do
     subject.prefix("my/awesome/api")
-    subject.settings[:prefix].should == "my/awesome/api"
-  end
-
-  it "considers prefix and version when building paths" do
-    subject.settings.merge!(:prefix => "api", :version => "v1")
-    subject.mount_path("users").should == "/api/v1/users"
+    subject.option(:prefix).should == "my/awesome/api"
   end
 
   it "stores middleware" do
     subject.use Rack::Auth::Basic
-    subject.settings[:middlewares].should == [[Rack::Auth::Basic]]
+    subject.option(:middlewares, :merge).should == [[Rack::Auth::Basic]]
   end
 
   it "stores basic auth info" do
     handler = proc {}
 
     subject.basic_auth("Get out!", &handler)
-    subject.settings[:auth].should == ["Get out!", handler]
+    subject.settings[:global][:auth].should == ["Get out!", handler]
   end
 end

data/spec/rack-api/settings_spec.rb

@@ -0,0 +1,50 @@
+require "spec_helper"
+
+describe Rack::API::Runner, "Settings" do
+  it "uses global namespace when no version is defined" do
+    subject.set :foo, :bar
+    subject.settings[:global][:foo].should == :bar
+  end
+
+  it "uses local namespace when version is defined" do
+    subject.settings[:version] = "v1"
+    subject.set :foo, :bar
+
+    subject.settings[:foo].should == :bar
+  end
+
+  it "appends item when mode is :append" do
+    subject.settings[:global][:list] = []
+    subject.set :list, :item, :append
+
+    subject.settings[:global][:list].should == [:item]
+  end
+
+  it "overrides item when mode is :override" do
+    subject.settings[:global][:list] = []
+    subject.set :list, [:item], :override
+
+    subject.settings[:global][:list].should == [:item]
+  end
+
+  it "returns global value" do
+    subject.set :name, "John Doe"
+    subject.option(:name).should == "John Doe"
+  end
+
+  it "returns local value" do
+    subject.settings[:version] = "v1"
+    subject.set :name, "John Doe"
+
+    subject.option(:name).should == "John Doe"
+  end
+
+  it "prefers local setting over global one" do
+    subject.set :name, "Mary Doe"
+
+    subject.settings[:version] = "v1"
+    subject.set :name, "John Doe"
+
+    subject.option(:name).should == "John Doe"
+  end
+end

metadata

@@ -2,7 +2,7 @@
 name: rack-api
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Nando Vieira
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-04-07 00:00:00 Z
+date: 2011-04-08 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rack
@@ -96,7 +96,9 @@ files:
 - Rakefile
 - examples/basic_auth.rb
 - examples/custom_class.rb
+- examples/custom_format.rb
 - examples/custom_headers.rb
+- examples/formats.rb
 - examples/middleware.rb
 - examples/multiple_versions.rb
 - examples/params.rb
@@ -106,6 +108,8 @@ files:
 - lib/rack/api/formatter.rb
 - lib/rack/api/formatter/base.rb
 - lib/rack/api/formatter/jsonp.rb
+- lib/rack/api/middleware.rb
+- lib/rack/api/middleware/format.rb
 - lib/rack/api/response.rb
 - lib/rack/api/runner.rb
 - lib/rack/api/version.rb
@@ -113,12 +117,14 @@ files:
 - spec/rack-api/basic_auth_spec.rb
 - spec/rack-api/format_spec.rb
 - spec/rack-api/headers_spec.rb
+- spec/rack-api/helpers_spec.rb
 - spec/rack-api/http_methods_spec.rb
 - spec/rack-api/inheritance_spec.rb
 - spec/rack-api/middlewares_spec.rb
 - spec/rack-api/params_spec.rb
 - spec/rack-api/paths_spec.rb
 - spec/rack-api/runner_spec.rb
+- spec/rack-api/settings_spec.rb
 - spec/rack-api/short_circuit_spec.rb
 - spec/spec_helper.rb
 - spec/support/awesome_middleware.rb
@@ -156,12 +162,14 @@ test_files:
 - spec/rack-api/basic_auth_spec.rb
 - spec/rack-api/format_spec.rb
 - spec/rack-api/headers_spec.rb
+- spec/rack-api/helpers_spec.rb
 - spec/rack-api/http_methods_spec.rb
 - spec/rack-api/inheritance_spec.rb
 - spec/rack-api/middlewares_spec.rb
 - spec/rack-api/params_spec.rb
 - spec/rack-api/paths_spec.rb
 - spec/rack-api/runner_spec.rb
+- spec/rack-api/settings_spec.rb
 - spec/rack-api/short_circuit_spec.rb
 - spec/spec_helper.rb
 - spec/support/awesome_middleware.rb