rack-api 0.1.0

data/.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+pkg
+tmp

data/.rspec

@@ -0,0 +1 @@
+--color --format documentation

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/Gemfile.lock

@@ -0,0 +1,49 @@
+PATH
+  remote: .
+  specs:
+    rack-api (0.1.0)
+      activesupport (~> 3.0.6)
+      rack (~> 1.2.1)
+      rack-mount (~> 0.6.14)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (3.0.6)
+    archive-tar-minitar (0.5.2)
+    columnize (0.3.2)
+    diff-lcs (1.1.2)
+    linecache19 (0.5.12)
+      ruby_core_source (>= 0.1.4)
+    rack (1.2.2)
+    rack-mount (0.6.14)
+      rack (>= 1.0.0)
+    rack-test (0.5.7)
+      rack (>= 1.0)
+    rspec (2.5.0)
+      rspec-core (~> 2.5.0)
+      rspec-expectations (~> 2.5.0)
+      rspec-mocks (~> 2.5.0)
+    rspec-core (2.5.1)
+    rspec-expectations (2.5.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.5.0)
+    ruby-debug-base19 (0.11.25)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby_core_source (0.1.5)
+      archive-tar-minitar (>= 0.5.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rack-api!
+  rack-test (~> 0.5.7)
+  rspec (~> 2.5.0)
+  ruby-debug19

data/README.rdoc

@@ -0,0 +1,54 @@
+= Rack::API
+
+Create web app APIs that respond to one or more formats using an elegant DSL.
+
+== Installation
+
+  gem install rack-api
+
+== Usage
+
+=== Basic example
+
+  Rack::API.app do
+    prefix "api"
+
+    version :v1 do
+      get "users(.:format)" do
+        User.all
+      end
+
+      get "users/:id(.:format)" do
+        User.find(params[:id])
+      end
+    end
+  end
+
+For additional examples, see https://github.com/fnando/rack-api/tree/master/examples.
+
+== Maintainer
+
+* Nando Vieira (http://nandovieira.com.br)
+
+== License
+
+(The MIT License)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,5 @@
+require "bundler"
+Bundler::GemHelper.install_tasks
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new

data/examples/basic_auth.rb

@@ -0,0 +1,22 @@
+$:.push(File.dirname(__FILE__) + "/../lib")
+
+# Just run `ruby examples/basic_auth.rb` and then use something like
+# `curl -u admin:test http://localhost:2345/api/v1/`.
+
+require "rack/api"
+
+Rack::API.app do
+  prefix "api"
+
+  basic_auth do |user, pass|
+    user == "admin" && pass == "test"
+  end
+
+  version :v1 do
+    get "/" do
+      {:message => "Hello, awesome API!"}
+    end
+  end
+end
+
+Rack::Handler::Thin.run Rack::API, :Port => 2345

data/examples/custom_class.rb

@@ -0,0 +1,28 @@
+$:.push(File.dirname(__FILE__) + "/../lib")
+
+# Just run `ruby examples/custom_class.rb` and then use something like
+# `curl http://localhost:2345/api/v1/` and `curl http://localhost:2345/api/v2/`.
+
+require "rack/api"
+
+class MyApp < Rack::API
+  prefix "api"
+
+  version :v1 do
+    get "/" do
+      {:message => "Using API v1"}
+    end
+  end
+end
+
+class MyApp < Rack::API
+  prefix "api"
+
+  version :v2 do
+    get "/" do
+      {:message => "Using API v2"}
+    end
+  end
+end
+
+Rack::Handler::Thin.run MyApp, :Port => 2345

data/examples/custom_headers.rb

@@ -0,0 +1,19 @@
+$:.push(File.dirname(__FILE__) + "/../lib")
+
+# Just run `ruby examples/custom_headers.rb` and then use something like
+# `curl -i http://localhost:2345/api/v1/`.
+
+require "rack/api"
+
+Rack::API.app do
+  prefix "api"
+
+  version :v1 do
+    get "/" do
+      headers["X-Awesome"] = "U R Awesome!"
+      {:message => "Hello, awesome API!"}
+    end
+  end
+end
+
+Rack::Handler::Thin.run Rack::API, :Port => 2345

data/examples/middleware.rb

@@ -0,0 +1,34 @@
+$:.push(File.dirname(__FILE__) + "/../lib")
+
+# Just run `ruby examples/middleware.rb` and then use something like
+# `curl http://localhost:2345/api/v1/`.
+
+require "rack/api"
+require "json"
+
+class ResponseTime
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    start = Time.now
+    status, headers, response = @app.call(env)
+    elapsed = Time.now - start
+    response = JSON.load(response.first).merge(:response_time => elapsed)
+    [status, headers, [response.to_json]]
+  end
+end
+
+Rack::API.app do
+  prefix "api"
+  use ResponseTime
+
+  version :v1 do
+    get "/" do
+      {:message => "Hello, awesome API!"}
+    end
+  end
+end
+
+Rack::Handler::Thin.run Rack::API, :Port => 2345

data/examples/multiple_versions.rb

@@ -0,0 +1,24 @@
+$:.push(File.dirname(__FILE__) + "/../lib")
+
+# Just run `ruby examples/multiple_versions.rb` and then use something like
+# `curl http://localhost:2345/api/v1/` and `curl http://localhost:2345/api/v2`.
+
+require "rack/api"
+
+Rack::API.app do
+  prefix "api"
+
+  version :v1 do
+    get "/" do
+      {:message => "You're using API v1"}
+    end
+  end
+
+  version :v2 do
+    get "/" do
+      {:message => "You're using API v2"}
+    end
+  end
+end
+
+Rack::Handler::Thin.run Rack::API, :Port => 2345

data/examples/params.rb

@@ -0,0 +1,18 @@
+$:.push(File.dirname(__FILE__) + "/../lib")
+
+# Just run `ruby examples/params.rb` and then use something like
+# `curl http://localhost:2345/api/v1/hello/John`.
+
+require "rack/api"
+
+Rack::API.app do
+  prefix "api"
+
+  version :v1 do
+    get "/hello/:name" do
+      {:message => "Hello, #{params[:name]}"}
+    end
+  end
+end
+
+Rack::Handler::Thin.run Rack::API, :Port => 2345

data/examples/simple.rb

@@ -0,0 +1,18 @@
+$:.push(File.dirname(__FILE__) + "/../lib")
+
+# Just run `ruby examples/simple.rb` and then use something like
+# `curl http://localhost:2345/api/v1/`.
+
+require "rack/api"
+
+Rack::API.app do
+  prefix "api"
+
+  version :v1 do
+    get "/" do
+      {:message => "Hello, awesome API!"}
+    end
+  end
+end
+
+Rack::Handler::Thin.run Rack::API, :Port => 2345

data/lib/rack/api/app.rb

@@ -0,0 +1,162 @@
+module Rack
+  class API
+    class App
+      # Registered content types. If you want to use
+      # a custom formatter that is not listed here,
+      # you have to manually add it. Otherwise,
+      # Rack::API::App::DEFAULT_MIME_TYPE will be used
+      # as the content type.
+      #
+      MIME_TYPES = {
+        "json"  => "application/json",
+        "jsonp" => "application/javascript",
+        "xml"   => "application/xml",
+        "rss"   => "application/rss+xml",
+        "atom"  => "application/atom+xml",
+        "html"  => "text/html",
+        "yaml"  => "application/x-yaml",
+        "txt"   => "text/plain"
+      }
+
+      # Default content type. Will be used when a given format
+      # hasn't been registered on Rack::API::App::MIME_TYPES.
+      #
+      DEFAULT_MIME_TYPE = "application/octet-stream"
+
+      attr_reader :block
+      attr_reader :env
+
+      # Hold block that will be executed in case the
+      # route is recognized.
+      #
+      def initialize(options)
+        options.each do |name, value|
+          instance_variable_set("@#{name}", value)
+        end
+      end
+
+      # Always log to the standard output.
+      #
+      def logger
+        @logger ||= Logger.new(STDOUT)
+      end
+
+      # Hold headers that will be sent on the response.
+      #
+      def headers
+        @headers ||= {}
+      end
+
+      # Merge all params into one single hash.
+      #
+      def params
+        @params ||= HashWithIndifferentAccess.new(request.params.merge(env["rack.routing_args"]))
+      end
+
+      # Return a request object.
+      #
+      def request
+        @request ||= Rack::Request.new(env)
+      end
+
+      # Return the requested format. Defaults to JSON.
+      #
+      def format
+        params.fetch(:format, "json")
+      end
+
+      # Stop processing by rendering the provided information.
+      #
+      #   Rack::API.app do
+      #     version :v1 do
+      #       get "/" do
+      #         error(:status => 403, :message => "Not here!")
+      #       end
+      #     end
+      #   end
+      #
+      # Valid options are:
+      #
+      # # <tt>:status</tt>: a HTTP status code. Defaults to 403.
+      # # <tt>:message</tt>: a message that will be rendered as the response body. Defaults to "Forbidden".
+      # # <tt>:headers</tt>: the response headers. Defaults to <tt>{"Content-Type" => "text/plain"}</tt>.
+      #
+      # You can also provide a object that responds to <tt>to_rack</tt>. In this case, this
+      # method must return a valid Rack response (a 3-item array).
+      #
+      #   class MyError
+      #     def self.to_rack
+      #       [500, {"Content-Type" => "text/plain"}, ["Internal Server Error"]]
+      #     end
+      #   end
+      #
+      #   Rack::API.app do
+      #     version :v1 do
+      #       get "/" do
+      #         error(MyError)
+      #       end
+      #     end
+      #   end
+      #
+      def error(options = {})
+        throw :error, Response.new(options)
+      end
+
+      # Set response status code.
+      #
+      def status(*args)
+        @status = args.first unless args.empty?
+        @status || 200
+      end
+
+      # Reset environment between requests.
+      #
+      def reset! # :nodoc:
+        @params = nil
+        @request = nil
+        @headers = nil
+      end
+
+      # Render the result of block.
+      #
+      def call(env) # :nodoc:
+        reset!
+        @env = env
+
+        response = catch(:error) do
+          render instance_eval(&block)
+        end
+
+        response.respond_to?(:to_rack) ? response.to_rack : response
+      end
+
+      # Return response content type based on extension.
+      # If you're using an unknown extension that wasn't registered on
+      # Rack::API::App::MIME_TYPES, it will return Rack::API::App::DEFAULT_MIME_TYPE,
+      # which defaults to <tt>application/octet-stream</tt>.
+      #
+      def content_type
+        mime = MIME_TYPES.fetch(format, DEFAULT_MIME_TYPE)
+        headers.fetch("Content-Type", mime)
+      end
+
+      private
+      def render(response) # :nodoc:
+        [status, headers.merge("Content-Type" => content_type), [format_response(response)]]
+      end
+
+      def format_response(response) # :nodoc:
+        formatter_name = format.split("_").collect {|word| word[0,1].upcase + word[1,word.size].downcase}.join("")
+
+        if Rack::API::Formatter.const_defined?(formatter_name)
+          formatter = Rack::API::Formatter.const_get(formatter_name).new(response, params)
+          formatter.to_format
+        elsif response.respond_to?("to_#{format}")
+          response.__send__("to_#{format}")
+        else
+          throw :error, Response.new(:status => 406, :message => "Unknown format")
+        end
+      end
+    end
+  end
+end

data/lib/rack/api/formatter/base.rb

@@ -0,0 +1,20 @@
+module Rack
+  class API
+    module Formatter
+      class Base
+        attr_accessor :object
+        attr_accessor :params
+
+        class AbstractMethodError < StandardError; end
+
+        def initialize(object, params)
+          @object, @params = object, params
+        end
+
+        def to_format
+          raise AbstractMethodError
+        end
+      end
+    end
+  end
+end

data/lib/rack/api/formatter/jsonp.rb

@@ -0,0 +1,11 @@
+module Rack
+  class API
+    module Formatter
+      class Jsonp < Base
+        def to_format
+          params.fetch(:callback, "callback") + "(#{object.to_json});"
+        end
+      end
+    end
+  end
+end

data/lib/rack/api/formatter.rb

@@ -0,0 +1,8 @@
+module Rack
+  class API
+    module Formatter
+      autoload :Base, "rack/api/formatter/base"
+      autoload :Jsonp, "rack/api/formatter/jsonp"
+    end
+  end
+end

data/lib/rack/api/response.rb

@@ -0,0 +1,21 @@
+module Rack
+  class API
+    class Response
+      attr_reader :options
+
+      def initialize(options)
+        @options = options
+      end
+
+      def to_rack
+        return options.to_rack if options.respond_to?(:to_rack)
+
+        [
+          options.fetch(:status, 403),
+          {"Content-Type" => "text/plain"}.merge(options.fetch(:headers, {})),
+          [options.fetch(:message, "Forbidden")]
+        ]
+      end
+    end
+  end
+end

data/lib/rack/api/runner.rb

@@ -0,0 +1,118 @@
+module Rack
+  class API
+    class Runner
+      HTTP_METHODS = %w[get post put delete head]
+
+      attr_accessor :settings
+
+      def initialize
+        @settings = {
+          :prefix      => "/",
+          :formats     => %w[json jsonp],
+          :middlewares => []
+        }
+      end
+
+      # Add a middleware to the execution stack.
+      #
+      def use(middleware, *args)
+        settings[:middlewares] << [middleware, *args]
+      end
+
+      # Set an additional url prefix.
+      #
+      def prefix(name)
+        settings[:prefix] = name
+      end
+
+      # Create a new API version.
+      #
+      def version(name, &block)
+        raise ArgumentError, "you need to pass a block" unless block_given?
+        settings[:version] = name.to_s
+        instance_eval(&block)
+        settings.delete(:version)
+      end
+
+      # Run all routes.
+      #
+      def call(env) # :nodoc:
+        route_set.freeze.call(env)
+      end
+
+      # Require basic authentication before processing other requests.
+      # The authentication reques must be defined before routes.
+      #
+      #   Rack::API.app do
+      #     basic_auth "Protected Area" do |user, pass|
+      #       User.authenticate(user, pass)
+      #     end
+      #   end
+      def basic_auth(realm = "Restricted Area", &block)
+        settings[:auth] = [realm, block]
+      end
+
+      # Define the formats that this app implements.
+      # Respond only to <tt>:json</tt> by default.
+      #
+      # When setting a format you have some alternatives on how this object
+      # will be formated.
+      #
+      # First, Rack::API will look for a formatter defined on Rack::API::Formatter
+      # namespace. If there's no formatter, it will look for a method <tt>to_<format></tt>.
+      # It will raise an exception if no formatter method has been defined.
+      #
+      # See Rack::API::Formatter::Jsonp for an example on how to create additional
+      # formatters.
+      #
+      def respond_to(*formats)
+        settings[:formats] = formats
+      end
+
+      # Hold all routes.
+      #
+      def route_set # :nodoc:
+        @route_set ||= Rack::Mount::RouteSet.new
+      end
+
+      # Define a new routing that will be triggered when both request method and
+      # path are recognized.
+      #
+      # You're better off using all verb shortcut methods. Implemented verbs are
+      # +get+, +post+, +put+, +delete+ and +head+.
+      #
+      #   class MyAPI < Rack::API
+      #     version "v1" do
+      #       get "users(.:format)" do
+      #         # do something
+      #       end
+      #     end
+      #   end
+      #
+      def route(method, path, requirements = {}, &block)
+        path = Rack::Mount::Strexp.compile mount_path(path), requirements, %w[ / . ? ]
+        route_set.add_route(build_app(block), :path_info => path, :request_method => method)
+      end
+
+      HTTP_METHODS.each do |method|
+        class_eval <<-RUBY, __FILE__, __LINE__
+          def #{method}(*args, &block)                # def get(*args, &block)
+            route("#{method.upcase}", *args, &block)  #   route("GET", *args, &block)
+          end                                         # end
+        RUBY
+      end
+
+      def mount_path(path) # :nodoc:
+        Rack::Mount::Utils.normalize_path([settings[:prefix], settings[:version], path].join("/"))
+      end
+
+      def build_app(block) # :nodoc:
+        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)
+        builder.to_app
+      end
+    end
+  end
+end

data/lib/rack/api/version.rb

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