rest-more

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:

Various REST clients such as Facebook and Twitter built with rest-core

FEATURES:

Out-of-box REST clients built with rest-core for:

• Bing
• Dropbox
• Facebook
• Flurry
• Github
• Linkedin
• Mixi
• Twitter

Rails utilities are also included.

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-more

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

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

SYNOPSIS:

The simplest usage:

    require 'rest-more'

    RestCore::Twitter.new.statuses('_cardinalblue') # get user tweets
    RestCore::Github.new.get('users/cardinalblue')  # get user info

    linkedin = RestCore::Linkedin.new(:consumer_key    => '...',
                                      :consumer_secret => '...')
    linkedin.authorize_url!   # copy and paste the URL in browser to authorize
    linkedin.authorize!('..') # paste your code from browser
    linkedin.me               # get current user info

    RestCore::Facebook.new.get('4') # get user info

Runnable example is here: example/simple.rb. Please see 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. By default, all clients are using RestClient, which is a synchronous HTTP client, thus blocking. It's very easy to use, but not very scalable (not concurrent-efficient). You can change the default app (i.e. HTTP clients) to an asynchronous one:

    require 'rest-more'
    RestCore::Builder.default_app = RestCore::EmHttpRequest

or an auto-picking one, which would try to infer the correct HTTP client depending on the context. Either em-http-request, cool.io-http, or even rest-client if none of reactors is available.

    require 'rest-more'
    RestCore::Builder.default_app = RestCore::Auto

You can also setup the default_app for a specific client, so that it won't change all the default_app for all the clients, like this:

    require 'rest-more'
    RestCore::Facebook.builder.default_app = RestCore::Auto

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.

    require 'rest-more'
    require 'eventmachine'
    RestCore::Builder.default_app = RestCore::EmHttpRequest
    EM.run{
      RestCore::Facebook.new.get('4'){ |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.

    require 'rest-more'
    require 'eventmachine'

    RestCore::Builder.default_app = RestCore::EmHttpRequest

    EM.run{
      Fiber.new{
        p RestCore::Facebook.new.get('4')
        EM.stop
      }.resume
      puts "It's not blocking..."
    }

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

    require 'rest-more'
    require 'eventmachine'

    RestCore::Builder.default_app = RestCore::Auto
    facebook = RestCore::Facebook.new(:log_method => method(:puts))

    EM.run{
      Fiber.new{
        fiber = Fiber.current
        result = {}
        facebook.get('4'){ |response|
          result[0] = response
          fiber.resume(result) if result.size == 2
        }
        puts "It's not blocking..."
        facebook.get('4'){ |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. All RestCore::EmHttpRequest above is interchangeable with RestCore::Auto because RestCore::Auto would pick the right HTTP client when running inside the eventmachine's event loop.

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)

Rails Utilities

To be added. But you can take a look at the Facebook tutorial first.

EventMachine inside Rainbows!

To be added. But you can take a look at the Rainbows configuration first.

A simple interactive shell with rib:

You need to install rib in order to try this interactive shell:

gem install rib

Then you can try this by running rib rest-core:

rest-core>> self.site = 'https://api.github.com/users/'
rest-core>> self.json_decode = true
rest-core>> get 'cardinalblue'

Which is using RestCore::Universal for accessing arbitrary websites.

rest-more users:

• s2sync
• s2sync_web

Powered sites:

• PicCollage

CHANGES:

• CHANGES

CONTRIBUTORS:

• ayaya (@ayamomiji)
• Lin Jen-Shin (@godfat)
• Yun-Yan Chi (@jaiyalas)

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.