Rack middleware which extends Grape::API to support request batching.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib/grape
spec
.gitignore
.rspec
.rubocop.yml
.ruby-gemset
.ruby-version
.travis.yml
CHANGELOG.md
Gemfile
LICENSE.txt
README.md
Rakefile
grape-batch.gemspec

README.md

Grape::Batch

Rack middleware which extends Grape::API to support request batching.

Build status

Installation

Add this line to your application's Gemfile:

gem 'grape-batch'

And then execute:

$ bundle

Or install it yourself as:

$ gem install grape-batch

Usage

General considerations

This middleware is intended to be used with JSON Grape::API only.

Rails apps

  1. Create an initializer and add you configuration 'config/initializers/grape-batch.rb'
  2. Add the middleware to the stack
# config/application.rb
Rails.application.configure do
 # rest of the file is hidden
 config.middleware.use Grape::Batch::Base
end

Sinatra and other Rack apps

# config.ru
require 'grape/batch'
use Grape::Batch::Base

Settings

Override any of these defaults in config/initializers/grape_batch.rb:

Grape::Batch.configure do |config|
  config.limit = 10
  config.path = '/batch'
  config.formatter = Grape::Batch::Response
  config.logger = nil
  config.session_proc = Proc.new {}
end
Argument Type Default Description
limit integer 10  Maximum number of batched requests allowed by the middleware
path string  /batch Route on which the middleware is mounted on
formatter class  Grape::Batch::Response The response formatter to use

Response formatter

#####Default format (success)

{success: RESOURCE_RESPONSE}

#####Default format (failure)

{code: HTTP_STATUS_CODE, error: ERROR_MESSAGE}

Can be inherited easily.

class MyFormatter < Grape::Batch::Response
  def self.format(status, headers, body)
    # My awesome formatting
  end
end

Input format

POST http request on the default URL with a similar body:

{
  requests: 
    [
      {
        method: 'GET', 
        path: '/api/v1/users'
      },
      {
        method: 'POST', 
        path: '/api/v1/login',
        body: { token: 'nrg55xwrd45' }
      }
    ]
}

'body' is optional.

Sessions

Single authentication

It's possible ensure a single session during the execution of the batch. You have to specify your session Proc. Before running the batch, the Proc is executed (with env as argument) and stored in rack env 'api.session' key.

# Example
# Considering the config
Grape::Batch.configure do |config|
  config.session_proc = Proc.new {|env| User.where(token: env['HTTP_X_TOKEN']).first }
end

# You can build a Grape helper like this
module AuthHelpers
  def current_user
    if env['api.session']
      env['api.session']
    else
      # do authentication stuff
    end
  end
end

Authentication during request batch

It is possible to either keep a token (or a session) generated by a request of the batch and pass it to the following ones.

# Token example
# Considering this API
module Twitter
  class API < Grape::API
    version 'v1', using: :path
    format :json
    prefix 'api'
    
    resource :session do
        get do
            # route logic
            request.env['HTTP_X_API_TOKEN'] = 'my_fresh_token'
            # some other logic
        end
    end
end

# This route will register a token. The header will be kept and passed to the following requests by Grape::Batch. 
# Session example
# Considering this API
module Twitter
  class API < Grape::API
    version 'v1', using: :path
    format :json
    prefix 'api'
    
    resource :session do
        get do
            # route logic            
            request.env['api.session'] = OpenStruct(id: '123456')
            # some other logic
        end
    end
end

# This route will return a session object. The session object will be kept and passed to the following requests by Grape::Batch.  

Contributing

  1. Fork it ( https://github.com/c4mprod/grape-batch/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request