rack-api 0.1.0

data/lib/rack/api.rb

@@ -0,0 +1,83 @@
+require "rack"
+require "rack/mount"
+require "active_support/hash_with_indifferent_access"
+require "json"
+require "logger"
+
+module Rack
+  class API
+    autoload :App, "rack/api/app"
+    autoload :Formatter, "rack/api/formatter"
+    autoload :Runner, "rack/api/runner"
+    autoload :Response, "rack/api/response"
+    autoload :Version, "rack/api/version"
+
+    # 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.
+    #
+    #   Rack::API.app do
+    #     # define your API
+    #   end
+    #
+    def self.app(&block)
+      runner.instance_eval(&block)
+      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!
+      @runner = nil
+    end
+
+    # Required by Rack.
+    #
+    def self.call(env) # :nodoc:
+      runner.call(env)
+    end
+
+    private
+    # Initialize a new Rack::API::Middleware instance, so
+    # we can use it on other class methods.
+    #
+    def self.runner
+      @runner ||= Runner.new
+    end
+  end
+end

data/rack-api.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "rack/api"
+
+Gem::Specification.new do |s|
+  s.name        = "rack-api"
+  s.version     = Rack::API::Version::STRING
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Nando Vieira"]
+  s.email       = ["fnando.vieira@gmail.com"]
+  s.homepage    = "http://rubygems.org/gems/rack-api"
+  s.summary     = "Create web app APIs that respond to one or more formats using an elegant DSL."
+  s.description = s.summary
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency "rack", "~> 1.2.1"
+  s.add_dependency "rack-mount", "~> 0.6.14"
+  s.add_dependency "activesupport", "~> 3.0.6"
+  s.add_development_dependency "rspec", "~> 2.5.0"
+  s.add_development_dependency "rack-test", "~> 0.5.7"
+  s.add_development_dependency "ruby-debug19" if RUBY_VERSION >= "1.9"
+end

data/spec/rack-api/basic_auth_spec.rb

@@ -0,0 +1,30 @@
+require "spec_helper"
+
+describe Rack::API, "Basic Authentication" do
+   before do
+    Rack::API.app do
+      version :v1 do
+        basic_auth do |user, pass|
+          user == "admin" && pass == "test"
+        end
+
+        get("/") { {:success => true} }
+      end
+    end
+  end
+
+  it "denies access" do
+    get "/v1/"
+    last_response.status.should == 401
+
+    get "/v1/", {}, "HTTP_AUTHORIZATION" => basic_auth("admin", "invalid")
+    last_response.status.should == 401
+  end
+
+  it "grants access" do
+    get "/v1/", {}, "HTTP_AUTHORIZATION" => basic_auth("admin", "test")
+
+    last_response.status.should == 200
+    JSON.load(last_response.body).should == {"success" => true}
+  end
+end

data/spec/rack-api/format_spec.rb

@@ -0,0 +1,110 @@
+require "spec_helper"
+
+describe Rack::API, "Format" do
+   before do
+    Rack::API.app do
+      version :v1 do
+        respond_to :json, :jsonp, :awesome, :fffuuu, :zomg
+        get("/") { {:success => true} }
+        get("users(.:format)") { {:users => []} }
+      end
+    end
+  end
+
+  it "ignores unknown formats" do
+    get "/users.xml"
+    last_response.status.should == 404
+  end
+
+  context "missing formatter" do
+    it "renders 406" do
+      get "/v1/users.zomg"
+
+      last_response.status.should == 406
+      last_response.body.should == "Unknown 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"
+
+      last_response.status.should == 200
+      last_response.body.should == %[callback({"success":true});]
+    end
+
+    it "renders when set through extension" do
+      get "/v1/users.jsonp"
+
+      last_response.status.should == 200
+      last_response.body.should == %[callback({"users":[]});]
+    end
+
+    it "sends header" do
+      get "/v1/users.jsonp"
+      last_response.headers["Content-Type"].should == "application/javascript"
+    end
+  end
+
+  context "JSON" do
+    it "renders when set through query string" do
+      get "/v1", :format => "json"
+
+      last_response.status.should == 200
+      JSON.load(last_response.body).should == {"success" => true}
+    end
+
+    it "renders when set through extension" do
+      get "/v1/users.json"
+
+      last_response.status.should == 200
+      JSON.load(last_response.body).should == {"users" => []}
+    end
+
+    it "sends header" do
+      get "/v1/users.json"
+      last_response.headers["Content-Type"].should == "application/json"
+    end
+  end
+
+  context "custom formatter extension" do
+    it "renders when set through query string" do
+      get "/v1", :format => "awesome"
+
+      last_response.status.should == 200
+      last_response.body.should == "U R Awesome"
+    end
+
+    it "renders when set through extension" do
+      get "/v1/users.awesome"
+
+      last_response.status.should == 200
+      last_response.body.should == "U R Awesome"
+    end
+  end
+
+  context "custom formatter class" do
+    before :all do
+      Rack::API::Formatter::Fffuuu = Class.new(Rack::API::Formatter::Base) do
+        def to_format
+          "ZOMG! Fffuuu!"
+        end
+      end
+    end
+
+    it "renders when set through query string" do
+      get "/v1", :format => "fffuuu"
+
+      last_response.status.should == 200
+      last_response.body.should == "ZOMG! Fffuuu!"
+    end
+
+    it "renders when set through extension" do
+      get "/v1/users.fffuuu"
+
+      last_response.status.should == 200
+      last_response.body.should == "ZOMG! Fffuuu!"
+    end
+  end
+end

data/spec/rack-api/headers_spec.rb

@@ -0,0 +1,24 @@
+require "spec_helper"
+
+describe Rack::API, "Headers" do
+   before do
+    Rack::API.app do
+      version :v1 do
+        get("/users(.:format)") do
+          headers["X-Awesome"] = "U R Awesome"
+          headers["Content-Type"] = "application/x-json"
+        end
+      end
+    end
+  end
+
+  it "sends custom headers" do
+    get "/v1/users"
+    last_response.headers["X-Awesome"].should == "U R Awesome"
+  end
+
+  it "overrides inferred content type" do
+    get "/v1/users.json"
+    last_response.headers["Content-Type"].should == "application/x-json"
+  end
+end

data/spec/rack-api/http_methods_spec.rb

@@ -0,0 +1,28 @@
+require "spec_helper"
+
+describe Rack::API, "HTTP Methods" do
+   before do
+    Rack::API.app do
+      version :v1 do
+        get("get") { {:get => true} }
+        post("post") { {:post => true} }
+        put("put") { {:put => true} }
+        delete("delete") { {:delete => true} }
+        head("head") { {:head => true} }
+      end
+    end
+  end
+
+  Rack::API::Runner::HTTP_METHODS.each do |method|
+    it "renders #{method}" do
+      send method, "/v1/#{method}"
+      last_response.status.should == 200
+      JSON.load(last_response.body).should == {method => true}
+    end
+  end
+
+  it "does not render unknown methods" do
+    post "/get"
+    last_response.status.should == 404
+  end
+end

data/spec/rack-api/inheritance_spec.rb

@@ -0,0 +1,12 @@
+require "spec_helper"
+
+describe Rack::API do
+  before do
+    @app = MyApp
+  end
+
+  it "renders action from MyApp" do
+    get "/v1"
+    JSON.load(last_response.body).should == {"myapp" => true}
+  end
+end

data/spec/rack-api/middlewares_spec.rb

@@ -0,0 +1,17 @@
+require "spec_helper"
+
+describe Rack::API, "Middlewares" do
+   before do
+    Rack::API.app do
+      version :v1 do
+        use AwesomeMiddleware
+        get("/") {}
+      end
+    end
+  end
+
+  it "sends custom headers" do
+    get "/v1"
+    last_response.headers["X-Awesome"].should == "U R Awesome"
+  end
+end

data/spec/rack-api/params_spec.rb

@@ -0,0 +1,27 @@
+require "spec_helper"
+
+describe Rack::API, "Params" do
+   before do
+    Rack::API.app do
+      version :v1 do
+        get("users/:id(.:format)") { params }
+        post("users") { params }
+      end
+    end
+  end
+
+  it "detects optional names from routing params" do
+    get "/v1/users/1.json"
+    JSON.load(last_response.body).should == {"id" => "1", "format" => "json"}
+  end
+
+  it "detects query string params" do
+    get "/v1/users/1?include=articles"
+    JSON.load(last_response.body).should == {"id" => "1", "include" => "articles"}
+  end
+
+  it "detects post params" do
+    post "/v1/users", :name => "John Doe"
+    JSON.load(last_response.body).should == {"name" => "John Doe"}
+  end
+end

data/spec/rack-api/paths_spec.rb

@@ -0,0 +1,35 @@
+require "spec_helper"
+
+describe Rack::API, "Paths" do
+   before do
+    Rack::API.app do
+      version :v1 do
+        prefix "api"
+        get("users") { {:users => []} }
+      end
+
+      version :v2 do
+        prefix "/"
+        get("users") { {:users => []} }
+      end
+    end
+  end
+
+  it "does not render root" do
+    get "/"
+    last_response.status.should == 404
+  end
+
+  it "does not render unknown paths" do
+    get "/api/v1/users/index"
+    last_response.status.should == 404
+  end
+
+  it "renders known paths" do
+    get "/api/v1/users"
+    last_response.status.should == 200
+
+    get "/v2/users"
+    last_response.status.should == 200
+  end
+end

data/spec/rack-api/runner_spec.rb

@@ -0,0 +1,38 @@
+require "spec_helper"
+
+describe Rack::API::Runner do
+  it "responds to http methods" do
+    subject.should respond_to(:get)
+    subject.should respond_to(:post)
+    subject.should respond_to(:put)
+    subject.should respond_to(:delete)
+    subject.should respond_to(:head)
+  end
+
+  it "sets available formats" do
+    subject.respond_to(:json, :jsonp, :atom)
+    subject.settings[: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"
+  end
+
+  it "stores middleware" do
+    subject.use Rack::Auth::Basic
+    subject.settings[:middlewares].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]
+  end
+end

data/spec/rack-api/short_circuit_spec.rb

@@ -0,0 +1,33 @@
+require "spec_helper"
+
+describe Rack::API, "Short circuit" do
+  before do
+    Rack::API.app do
+      version :v1 do
+        get("/") { error :status => 412, :headers => {"X-Awesome" => "UR NO Awesome"}, :message => "ZOMG! Nothing to see here!" }
+        get("/custom") do
+          error_message = Object.new
+          def error_message.to_rack
+            [412, {"X-Awesome" => "UR NO Awesome Indeed"}, ["Keep going!"]]
+          end
+
+          error(error_message)
+        end
+      end
+    end
+  end
+
+  it "renders hash error" do
+    get "/v1"
+    last_response.status.should == 412
+    last_response.headers["X-Awesome"].should == "UR NO Awesome"
+    last_response.body.should == "ZOMG! Nothing to see here!"
+  end
+
+  it "renders object#to_rack method" do
+    get "/v1/custom"
+    last_response.status.should == 412
+    last_response.headers["X-Awesome"].should == "UR NO Awesome Indeed"
+    last_response.body.should == "Keep going!"
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+require "rack/test"
+require "rspec"
+require "rack/api"
+require "base64"
+
+Dir[File.dirname(__FILE__) + "/support/**/*.rb"].each {|file| require file}
+
+RSpec.configure do |config|
+  config.include Rack::Test::Methods
+  config.include Helpers
+
+  config.before { Rack::API.reset! }
+end

data/spec/support/awesome_middleware.rb

@@ -0,0 +1,10 @@
+class AwesomeMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    status, headers, response = @app.call(env)
+    [status, headers.merge("X-Awesome" => "U R Awesome"), response]
+  end
+end

data/spec/support/core_ext.rb

@@ -0,0 +1,5 @@
+class Hash
+  def to_awesome
+    "U R Awesome"
+  end
+end

data/spec/support/helpers.rb

@@ -0,0 +1,9 @@
+module Helpers
+  def app
+    @app ||= Rack::API
+  end
+
+  def basic_auth(username, password)
+    "Basic " + Base64.encode64("#{username}:#{password}")
+  end
+end

data/spec/support/myapp.rb

@@ -0,0 +1,7 @@
+class MyApp < Rack::API
+  version :v1 do
+    get "/" do
+      {:myapp => true}
+    end
+  end
+end

metadata

@@ -0,0 +1,170 @@
+--- !ruby/object:Gem::Specification 
+name: rack-api
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Nando Vieira
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-04-07 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rack
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.2.1
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rack-mount
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.6.14
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 3.0.6
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 2.5.0
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rack-test
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.5.7
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: ruby-debug19
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id006
+description: Create web app APIs that respond to one or more formats using an elegant DSL.
+email: 
+- fnando.vieira@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .rspec
+- Gemfile
+- Gemfile.lock
+- README.rdoc
+- Rakefile
+- examples/basic_auth.rb
+- examples/custom_class.rb
+- examples/custom_headers.rb
+- examples/middleware.rb
+- examples/multiple_versions.rb
+- examples/params.rb
+- examples/simple.rb
+- lib/rack/api.rb
+- lib/rack/api/app.rb
+- lib/rack/api/formatter.rb
+- lib/rack/api/formatter/base.rb
+- lib/rack/api/formatter/jsonp.rb
+- lib/rack/api/response.rb
+- lib/rack/api/runner.rb
+- lib/rack/api/version.rb
+- rack-api.gemspec
+- spec/rack-api/basic_auth_spec.rb
+- spec/rack-api/format_spec.rb
+- spec/rack-api/headers_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/short_circuit_spec.rb
+- spec/spec_helper.rb
+- spec/support/awesome_middleware.rb
+- spec/support/core_ext.rb
+- spec/support/helpers.rb
+- spec/support/myapp.rb
+homepage: http://rubygems.org/gems/rack-api
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.7.2
+signing_key: 
+specification_version: 3
+summary: Create web app APIs that respond to one or more formats using an elegant DSL.
+test_files: 
+- spec/rack-api/basic_auth_spec.rb
+- spec/rack-api/format_spec.rb
+- spec/rack-api/headers_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/short_circuit_spec.rb
+- spec/spec_helper.rb
+- spec/support/awesome_middleware.rb
+- spec/support/core_ext.rb
+- spec/support/helpers.rb
+- spec/support/myapp.rb