batch_api 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 YOURNAME
+
+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,30 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'BatchApi'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = ["--color", '--format doc', '--order rand']
+end
+
+task :default => :spec

data/app/controllers/batch_api/batch_controller.rb

@@ -0,0 +1,10 @@
+require 'batch_api/operation'
+
+module BatchApi
+  class BatchController < ::ApplicationController
+    def batch
+      ops = params[:ops].map {|o| BatchApi::Operation.new(o, request.env)}
+      render :json => ops.map(&:execute)
+    end
+  end
+end

data/changelog.md

@@ -0,0 +1,2 @@
+v0.0.1
+* Initial build

data/lib/batch_api.rb

@@ -0,0 +1,6 @@
+require 'batch_api/routing_helper'
+require 'batch_api/engine'
+require 'batch_api/version'
+
+module BatchApi
+end

data/lib/batch_api/engine.rb

@@ -0,0 +1,8 @@
+# CURRENT FILE :: lib/team_page/engine.rb
+module BatchApi
+  class Engine < Rails::Engine
+    initializer "batch_api.add_routing_helper" do |app|
+      ActionDispatch::Routing::Mapper.send(:include, BatchApi::RoutingHelper)
+    end
+  end
+end

data/lib/batch_api/error.rb

@@ -0,0 +1,32 @@
+module BatchApi
+  # Public: an error thrown during a batch operation.
+  # This has a body class and a cookies accessor and can
+  # function in place of a regular BatchResponse object.
+  class Error
+    # Public: create a new BatchError from a Rails error.
+    def initialize(error)
+      @message = error.message
+      @backtrace = error.backtrace
+    end
+
+    # Public: here for compatibility with BatchResponse interface.
+    attr_reader :cookies
+
+    # Public: the error details as a hash, which can be returned
+    # to clients as JSON.
+    def body
+      if expose_backtrace?
+        {
+          message: @message,
+          backtrace: @backtrace
+        }
+      else
+        { message: @message }
+      end
+    end
+
+    def expose_backtrace?
+      Rails.env.production?
+    end
+  end
+end

data/lib/batch_api/operation.rb

@@ -0,0 +1,94 @@
+require 'batch_api/response'
+
+module BatchApi
+  # Public: an individual batch operation.
+  class Operation
+    attr_accessor :method, :url, :params, :headers
+    attr_accessor :env, :result
+
+    # Public: create a new Batch Operation given the specifications for a batch
+    # operation (as defined above) and the request environment for the main
+    # batch request.
+    def initialize(op, base_env)
+      @op = op
+
+      @method = op[:method]
+      @url = op[:url]
+      @params = op[:params]
+      @headers = op[:headers]
+
+      # deep_dup to avoid unwanted changes across requests
+      @env = base_env.deep_dup
+    end
+
+    # Execute a batch request, returning a BatchResponse object.  If an error
+    # occurs, it returns the same results as Rails would.
+    def execute
+      begin
+        action = identify_routing
+        process_env
+        BatchApi::Response.new(action.call(@env))
+      rescue => err
+        error_response(err)
+      end
+    end
+
+    # Internal: given a URL and other operation details as specified above,
+    # identify the appropriate controller and action to execute the action.
+    #
+    # Raises a routing error if the route doesn't exist.
+    #
+    # Returns the action object, which can be called with the environment.
+    def identify_routing
+      @path_params = Rails.application.routes.recognize_path(@url, @op)
+      @controller = ActionDispatch::Routing::RouteSet::Dispatcher.new.controller(@path_params)
+      @controller.action(@path_params[:action])
+    end
+
+    # Internal: customize the request environment.  This is currently done
+    # manually and feels clunky and brittle, but is mostly likely fine, though
+    # there are one or two environment parameters not yet adjusted.
+    def process_env
+      path, qs = @url.split("?")
+
+      # rails routing
+      @env["action_dispatch.request.path_parameters"] = @path_params
+      # this isn't quite right, but hopefully it'll work
+      # since we're not executing any middleware
+      @env["action_controller.instance"] = @controller.new
+
+      # Headers
+      headrs = (@headers || {}).inject({}) do |heads, (k, v)|
+        heads.tap {|h| h["HTTP_" + k.gsub(/\-/, "_").upcase] = v}
+      end
+      # preserve original headers unless explicitly overridden
+      @env.merge!(headrs)
+
+      # method
+      @env["REQUEST_METHOD"] = @method.upcase
+
+      # path and query string
+      @env["REQUEST_URI"] = @env["REQUEST_URI"].gsub(/\/batch.*/, @url)
+      @env["REQUEST_PATH"] = path
+      @env["ORIGINAL_FULLPATH"] = @env["PATH_INFO"] = @url
+
+      @env["rack.request.query_string"] = @env["QUERY_STRING"] = qs
+
+      # parameters
+      @env["action_dispatch.request.parameters"] = @params
+      @env["action_dispatch.request.request_parameters"] = @params
+      @env["rack.request.query_hash"] = @method == "get" ? @params : nil
+    end
+
+    # Internal: create a BatchResponse for an exception thrown during batch
+    # processing.
+    def error_response(err)
+      wrapper = ActionDispatch::ExceptionWrapper.new(@env, err)
+      BatchApi::Response.new([
+        wrapper.status_code,
+        {},
+        BatchApi::Error.new(err)
+      ])
+    end
+  end
+end

data/lib/batch_api/response.rb

@@ -0,0 +1,23 @@
+require 'batch_api/error'
+
+module BatchApi
+  # Public: a response from an internal operation in the Batch API.
+  # It contains all the details that are needed to describe the call's
+  # outcome.
+  class Response
+    # Public: the attributes of the HTTP response.
+    attr_accessor :status, :body, :headers, :cookies
+
+    # Public: create a new response representation from a Rack-compatible
+    # response (e.g. [status, headers, response_object]).
+    def initialize(response)
+      @status = response.first
+      @headers = response[1]
+
+      response_object = response[2]
+      @body = response_object.body
+      @cookies = response_object.cookies
+    end
+  end
+end
+

data/lib/batch_api/routing_helper.rb

@@ -0,0 +1,12 @@
+module BatchApi
+  module RoutingHelper
+    DEFAULT_VERB = :post
+    DEFAULT_ENDPOINT = "/batch"
+
+    def batch_api(options = {})
+      endpoint = options.delete(:endpoint) || DEFAULT_ENDPOINT
+      verb = options.delete(:via) || DEFAULT_VERB
+      match({endpoint => "batch_api/batch#batch", via: verb}.merge(options))
+    end
+  end
+end

data/lib/batch_api/version.rb

@@ -0,0 +1,3 @@
+module BatchApi
+  VERSION = "0.0.1"
+end

data/lib/tasks/batch_api_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :batch_api do
+#   # Task goes here
+# end

data/readme.md

@@ -0,0 +1,145 @@
+A proposal for a Batch API endpoint.
+
+Batch requests take the form of a series of REST API requests,
+each containing the following arguments:
+
+* _url_ - the API endpoint to hit, formatted exactly as you would for a regular
+REST API request (e.g. leading /, etc.)
+* _method_ - what type of request to make -- GET, POST, PUT, etc.
+* _args_ - a hash of arguments to the API. This can be used for both GET and
+PUT/POST/PATCH requests.
+* _headers_ - a hash of request-specific headers. (The headers sent in the
+request will be included as well, with request-specific headers taking
+precendence.)
+* _options_ - a hash of additional batch request options. There are currently
+none supported, but we plan to introduce some for dependency management,
+supressing output, etc. in the future.
+
+The Batch API endpoint itself (which lives at POST /batch) takes the
+following arguments:
+
+* _ops_ - an array of operations to perform, specified as described above.
+* _sequential_ - execute all operations sequentially, rather than in parallel.
+*THIS PARAMETER IS CURRENTLY REQUIRED AND MUST BE SET TO TRUE.* (In the future
+we'll offer parallel processing by default, and hence this parameter must be
+supplied in order topreserve expected behavior.
+
+Other options may be defined in the future.
+
+Users must be logged in to use the Batch API.
+
+The Batch API returns an array of results in the same order the operations are
+specified. Each result contains:
+
+* _status_ - the HTTP status (200, 201, 400, etc.)
+* _body_ - the rendered body
+* _headers_ - any response headers
+* _cookies_ - any cookies set by the request. (These will in the future be
+pulled into the main response to be processed by the client.)
+
+Errors in individual Batch API requests will be returned inline, with the
+same status code and body they would return as individual requests. If the
+Batch API itself returns a non-200 status code, that indicates a global
+problem:
+
+* _403_ - if the user isn't logged in
+* _422_ - if the batch request isn't properly formatted
+* _500_ - if there's an application error in the Batch API code
+
+** Examples **
+
+Given the following request:
+
+```ruby
+{
+  ops: [
+         {
+            method: "post",
+            url: "/resource/create",
+            args: {title: "bar", data: "foo"}
+          },
+          {
+            method: "get",
+            url: "/other_resource/123/connections"
+          },
+          {
+            method: "get",
+            url: "/i/gonna/throw/an/error",
+            header: { some: "headers" }
+          }
+       ]
+}
+```
+
+You'd get the following back:
+
+```ruby
+  [
+    {status: 201, body: "{json:\"data\"}", headers: {}, cookies: {}},
+    {status: 200, body: "[{json:\"data\"}, {more:\"data\"}]", headers: {}, cookies: {}},
+    {status: 500, body: "{error:\"message\"}", headers: {}, cookies: {}},
+  ]
+```
+
+** Implementation**
+
+For each request, we:
+* attempt to route it as Rails would (identifying controller and action)
+* create a customized request.env hash with the appropriate details
+* instantiate the controller and invoke the action
+* parse and process the result
+
+The overall result is then returned to the client.
+
+**Background**
+
+Batch APIs, though unRESTful, are useful for reducing HTTP overhead
+by combining requests; this is particularly valuable for mobile clients,
+which may generate groups of offline actions and which desire to
+reduce battery consumption while connected by making fewer, better-compressed
+requests.
+
+Generally, such interfaces fall into two categories:
+
+* a set of limited, specialized instructions, usually to manage resources
+* a general-purpose API that can take any operation the main API can
+handle
+
+The second approach minimizes code duplication and complexity. Rather than
+have two systems that manage resources (or a more complicated one that can
+handle both batch and individual requests), we simply route requests as we
+always would.
+
+This approach has several benefits:
+
+* Less complexity - non-batch endpoints don't need any extra code
+* Complete flexibility - as we add new features or endpoints to the API,
+they become immediately available via the Batch API.
+* More RESTful - as individual operations are simply actions on RESTful
+resources, we preserve an important characteristic of the API.
+
+As well as general benefits of using the Batch API:
+
+* Parallelizable - in the future, we could run requests in parallel (if
+our Rails app is running in thread-safe mode), allowing clients to
+specify explicit dependencies between operations (or run all
+sequentially).
+* Reuse of state - user authentication, request stack processing, and
+similar processing only needs to be done once.
+* Better for clients - fewer requests, better compressibility, etc.
+(as described above)
+
+There are two main downsides to our implementation:
+
+* Rails dependency - we use only public Rails interfaces, but these could
+still change with major updates. (_Resolution:_ with good testing we
+can identify changes and update code as needed.)
+* Reduced ability to optimize cross-request - unlike a specialized API,
+each request will be treated in isolation, and so you couldn't minimize
+DB updates through more complicated SQL logic. (_Resolution:_ none, but
+the main pain point currently is at the HTTP connection layer, so we
+accept this.)
+
+Once the Batch API is more developed, we'll spin it off into a gem, and
+possibly make it easy to create versions for Sinatra or other frameworks,
+if desired.

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: batch_api
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Alex Koppel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A Batch API plugin that provides a RESTful syntax, allowing clients to
+  make any number of REST calls with a single HTTP request.
+email:
+- alex@alexkoppel.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- app/controllers/batch_api/batch_controller.rb
+- lib/batch_api/engine.rb
+- lib/batch_api/error.rb
+- lib/batch_api/operation.rb
+- lib/batch_api/response.rb
+- lib/batch_api/routing_helper.rb
+- lib/batch_api/version.rb
+- lib/batch_api.rb
+- lib/tasks/batch_api_tasks.rake
+- MIT-LICENSE
+- Rakefile
+- changelog.md
+- readme.md
+homepage: http://github.com/arsduo/batch_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'
+      segments:
+      - 0
+      hash: -1071837955116255101
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -1071837955116255101
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.21
+signing_key: 
+specification_version: 3
+summary: A RESTful Batch API for Rails
+test_files: []