rest-core

by Cardinal Blue http://cardinalblue.com

Lin Jen-Shin (godfat) had given a talk about rest-core on RubyConf Taiwan 2011. The slide is in English, but the talk is in Mandarin.

You can also read some other topics at doc.

LINKS:

• github
• rubygems
• rdoc
• mailing list

DESCRIPTION:

Modular Ruby clients interface for REST APIs

There has been an explosion in the number of REST APIs available today. To address the need for a way to access these APIs easily and elegantly, we have developed rest-core, which consists of composable middleware that allows you to build a REST client for any REST API. Or in the case of common APIs such as Facebook, Github, and Twitter, you can simply use the dedicated clients provided by rest-more.

FEATURES:

• Modular interface for REST clients similar to WSGI/Rack for servers.
• Asynchronous/Synchronous styles with or without fibers are both supported.

REQUIREMENTS:

Mandatory:

• MRI (official CRuby) 1.8.7, 1.9.2, 1.9.3, Rubinius 1.8/1.9 and JRuby 1.8/1.9
• gem rest-client

Optional:

• Fibers only work on Ruby 1.9+
• gem em-http-request (if using eventmachine)
• gem cool.io-http (if using cool.io)
• gem json or yajl-ruby (if using JsonDecode middleware)

INSTALLATION:

    gem install rest-core

Or if you want development version, put this in Gemfile:

    gem 'rest-core', :git => 'git://github.com/cardinalblue/rest-core.git',
                     :submodules => true

If you just want to use Facebook or Twitter clients, please take a look at rest-more which has a lot of clients built with rest-core.

Build Your Own Clients:

You can use RestCore::Builder to build your own dedicated client:

    require 'rest-core'

    YourClient = RestCore::Builder.client do
      s = self.class # this is only for ruby 1.8!
      use s::DefaultSite , 'https://api.github.com/users/'
      use s::JsonDecode  , true
      use s::CommonLogger, method(:puts)
      use s::Cache       , nil, 3600
      run s::RestClient # the simplest and easier HTTP client
    end

And use it with per-instance basis (clients could have different configuration, e.g. different cache time or timeout time):

    client = YourClient.new(:cache => {})
    client.get('cardinalblue') # cache miss
    client.get('cardinalblue') # cache hit

    client.site = 'http://github.com/api/v2/json/user/show/'
    client.get('cardinalblue') # cache miss
    client.get('cardinalblue') # cache hit

Runnable example is here: example/rest-client.rb. Please see rest-more for more complex examples, and slides from rubyconf.tw/2011 for concepts.

Asynchronous HTTP Requests:

I/O bound operations shouldn't be blocking the CPU! If you have a reactor, i.e. event loop, you should take the advantage of that to make HTTP requests not block the whole process/thread. For now, we support eventmachine and cool.io. Below is an example for eventmachine:

    require 'rest-core'

    AsynchronousClient = RestCore::Builder.client do
      s = self.class # this is only for ruby 1.8!
      use s::DefaultSite , 'https://api.github.com/users/'
      use s::JsonDecode  , true
      use s::CommonLogger, method(:puts)
      use s::Cache       , nil, 3600
      run s::EmHttpRequest
    end

If you're passing a block, the block is called after the response is available. That is the block is the callback for the request.

    client = AsynchronousClient.new
    EM.run{
      client.get('cardinalblue'){ |response|
        p response
        EM.stop
      }
      puts "It's not blocking..."
    }

Otherwise, if you don't pass a block as the callback, EmHttpRequest (i.e. the HTTP client for eventmachine) would call Fiber.yield to yield to the original fiber, making asynchronous HTTP requests look like synchronous. If you don't understand what does this mean, you can take a look at em-synchrony. It's basically the same idea.

    EM.run{
      Fiber.new{
        p client.get('cardinalblue')
        EM.stop
      }.resume
      puts "It's not blocking..."
    }

Runnable example is here: example/eventmachine.rb. You can also make multi-requests synchronously like this:

    EM.run{
      Fiber.new{
        fiber = Fiber.current
        result = {}
        client.get('cardinalblue'){ |response|
          result[0] = response
          fiber.resume(result) if result.size == 2
        }
        client.get('cardinalblue'){ |response|
          result[1] = response
          fiber.resume(result) if result.size == 2
        }
        p Fiber.yield
        EM.stop
      }.resume
      puts "It's not blocking..."
    }

Runnable example is here: example/multi.rb.

Supported HTTP clients:

• RestCore::RestClient (gem rest-client)
• RestCore::EmHttpRequest (gem em-http-request)
• RestCore::Coolio (gem cool.io)
• RestCore::Auto (which would pick one of the above depending on the context)

Build Your Own Middlewares:

To be added.

Build Your Own HTTP clients:

To be added.

rest-core users:

• topcoder
• s2sync
• s2sync_web

Powered sites:

• PicCollage

CHANGES:

• CHANGES

GLOSSARY:

• A client is a class which can new connections to make requests. For instance, RestCore::Facebook.new.get('4')

• An app is an HTTP client which would do the underneath HTTP requests. For instance, RestCore::RestClient is an HTTP client which uses rest-client gem (::RestClient) to make HTTP requests.

• A middleware is a component for a rest-core stack. For instance, RestCore::DefaultSite is a middleware which would add default site URL in front of the request URI if it is not started with http://, thus you can do this: RestCore::Facebook.get('4') without specifying where the site (Facebook) it is.

• RestCore::Wrapper is a utility which could help you wrap a number of middlewares into another middleware. Currently, it's used in RestCore::Buidler and RestCore::Cache.

• RestCore::Builder is a utility which could help you build a client with a collection of middlewares and an app. i.e. a rest-core stack.

• RestCore::Middleware is a utility which could help you build a non-trivial middleware. More explanation to come...

• RestCore::Client is a module which would be included in a generated client by RestCore::Builder. It contains a number of convenient functions which is generally useful.

• RestCore::ClientOAuth1 is a module which should be included in a OAuth1.0 client. It contains a number of convenient functions which is useful for an OAuth 1.0 client.

• An env is a hash which contains all the information for both request and response. It's mostly seen in @app.call(env) See other explanation such as env[RestCore::REQUEST_METHOD] for more detail.

• env[RestCore::REQUEST_METHOD] is a symbol representing which HTTP method would be used in the subsequent HTTP request. The possible values are either: :get, :post, :put or :delete.

• env[RestCore::REQUEST_PATH] is a string representing which HTTP path would be used in the subsequent HTTP request. This path could also include the protocol, not only the path. e.g. "http://graph.facebook.com/4" or simply "4". In the case of built-in Facebook client, the RestCore::DefaultSite middleware would take care of the site.

• env[RestCore::REQUEST_QUERY] is a hash which keys are query keys and values are query values. Both keys and values' type should be String, not Symbol. Values with nil or false would be ignored. Both keys and values would be escaped automatically.

• env[RestCore::REQUEST_PAYLOAD] is a hash which keys are payload keys and values are payload values. Both keys and values' type should be String, not Symbol. Values with nil or false would be ignored. Both keys and values would be escaped automatically.

• env[RestCore::REQUEST_HEADERS] is a hash which keys are header names and values are header values. Both keys and values' type should be String, not Symbol. Values with nil or false would be ignored.

• env[RestCore::RESPONSE_BODY] is a string which is returned by the server. Might be nil if there's no response or not yet making HTTP request.

• env[RestCore::RESPONSE_STATUS] is a number which is returned by the server for the HTTP status. Might be nil if there's no response or not yet making HTTP request.

• env[RestCore::RESPONSE_HEADERS] is a hash which is returned by the server for the response headers. Both keys and values' type should be String.

• env[RestCore::DRY] is a boolean (either true or false or nil) which indicates that if we're only asking for modified env, instead of making real requests. It's used to ask for the real request URI, etc.

• env[RestCore::FAIL] is an array which contains failing events. Events could be any objects, it's handled by RestCore::ErrorDetector or any other custom middleware.

• env[RestCore::LOG] is an array which contains logging events. Events could be any objects, it's handled by RestCore::CommonLogger or any other custom middleware.

CONTRIBUTORS:

• Andrew Liu (@eggegg)
• andy (@coopsite)
• Barnabas Debreczeni (@keo)
• Bruce Chu (@bruchu)
• Ethan Czahor (@ethanz5)
• Florent Vaucelle (@florent)
• Jaime Cham (@jcham)
• John Fan (@johnfan)
• Lin Jen-Shin (@godfat)
• Mariusz Pruszynski (@snicky)
• Mr. Big Cat (@miaout17)
• Nicolas Fouché (@nfo)

LICENSE:

Apache License 2.0

Copyright (c) 2011-2012, Cardinal Blue

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.