一个类似 Facebook 的 RESTful 批量 API
A gem that provides a RESTful Batch API for Rails and other Rack applications. In this system, batch requests are simply collections of regular REST calls, whose results are returned as an equivalent collection of regular REST results.
This is heavily inspired by Facebook's Batch API.
Making a batch request:
# POST /batch
# Content-Type: application/json
{
ops: [
{method: "get", url: "/patrons"},
{method: "post", url: "/orders/new", params: {dish_id: 123}},
{method: "get", url: "/oh/no/error", headers: {break: "fast"}},
{method: "delete", url: "/patrons/456"}
],
sequential: true
}Reading the response:
{
results: [
{status: 200, body: [{id: 1, name: "Jim-Bob"}, ...], headers: {}},
{status: 201, body: {id: 4, dish_name: "Spicy Crab Legs"}, headers: {}},
{status: 500, body: {error: {oh: "noes!"}}, headers: {Problem: "woops"}},
{status: 200, body: null, headers: {}}}
]
}As you can see from the example above, each request in the batch (an "operation", in batch parlance) describes the same features any HTTP request would include:
These individual operations are supplied as the "ops" parameter in the overall request. Other options include:
Other options may be provided in the future for both the global request and individual operations.
The Batch API will always return a 200, with a JSON body containing the individual responses under the "results" key. Those responses, in turn, contain the same main components of any HTTP response:
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.
Setting up the Batch API is simple. Just add the gem to your middlewares:
# in application.rb
config.middleware.use BatchApi::RackMiddleware do |batch_config|
# you can set various configuration options:
batch_config.verb = :put # default :post
batch_config.endpoint = "/batchapi" # default /batch
batch_config.limit = 100 # how many operations max per request, default 50
# default middleware stack run for each batch request
batch_config.batch_middleware = Proc.new { }
# default middleware stack run for each individual operation
batch_config.operation_middleware = Proc.new { }
endThat's it! Just fire up your curl, hit your endpoint with the right verb and a properly formatted request, and enjoy some batch API action.
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.
HTTP pipelining is an awesome and promising technology, and would provide a simple and effortless way to parallel process many requests; however, using pipelining raised several issues for us, one of which was a blocker:
Given this state of affairs -- and my desire to hack up a Batch API gem :P --, we decided to implement an API-based solution.
There are two main approaches to writing batch APIs:
The second approach, IMO, 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 solution has several specific benefits:
As well as the general benefits of all batch operations:
There's only one downside I can think of to this approach as opposed to a specialized endpoint:
The Batch API is implemented as a Rack middleware. Here's how it works:
First, if the request isn't a batch request (as defined by the endpoint and method in BatchApi.config), it gets processed normally by your app.
If it is a batch request, we:
At both the batch level (processing all requests) and the individual operation request, there is an internal, customizable midleware stack that you can customize to insert additional custom behavior, such as handling authentication or decoding JSON bodies for individual requests (this latter comes pre-included). Check out the lib/batch_api/internal_middleware.rb for more information.
The core of the Batch API is complete and solid, and so ready to go that it's in use at 6Wunderkinder already :P
Here are some immediate tasks:
To 6Wunderkinder, for all their support for this open-source project, and their general awesomeness.
To Facebook, for providing inspiration and a great implementation in this and many other things.
To JT Archie for his help and feedback.
Open a ticket or send a pull request!
暂无开放 Issues,或尚未同步最近议题。