Skip to content
crohr edited this page Feb 17, 2012 · 5 revisions

What is Restfully

Restfully is a general-purpose client library for RESTful APIs. It is written in Ruby. Its goal is to abstract the nitty-gritty details of exchanging HTTP requests between the user-agent and the server. It also discovers resources at runtime, which means should the API change and add a new functionality, the client will automatically discover it.

In the next section we will describe how to install Restfully on various platforms.

Installation on UNIX systems

First, be sure you have a version of the Ruby_ interpreter on your system:

$ ruby -v
ruby 1.8.7 (2010-01-10 patchlevel 249) [i686-darwin10.2.0]

If that command returns an error, then you need to install Ruby. If you have a version lower than 1.8.6, you should probably consider upgrading to a newer version.

On recent distributions (e.g. Debian Squeeze), you should be able to install all the required dependencies with:

$ apt-get install ruby rubygems libxml2-dev libreadline-dev zlib1g-dev

Now, install Restfully:

$ gem install restfully --no-ri --no-rdoc

If you will be interacting with XML payloads, you should also install the libxml-ruby library:

$ gem install libxml-ruby --no-ri --no-rdoc

If you are working in the BonFIRE project, there is an additional package that can be installed for additional functionalities:

$ gem install restfully-addons --no-ri --no-rdoc

Now, test that you have access to the Restfully binary:

$ which restfully
/var/lib/gems/1.8/bin/restfully

On Debian Squeeze, you may need to add the path to the gem binaries to your $PATH:

$ export PATH="/var/lib/gems/1.8/bin:$PATH"

Installation on Windows

The following instructions successfully installed Restfully on Microsoft Windows XP.

Install Ruby

To install Ruby download the Ruby 1.8.7-pxxx RubyInstaller from http://rubyinstaller.org/downloads/.

Run this installer and install Ruby into C:\Ruby187\bin.

Add C:\Ruby187\bin to your path environment variable.

Install DevKit

Download and install DevKit as described in https://github.com/oneclick/rubyinstaller/wiki/Development-Kit.

Running the ruby commands mentioned stages 4 and 5 in that page produces output like the following:

C:\Documents and Settings\ahume>cd C:\DevKit

C:\DevKit>ruby dk.rb init
[INFO] found RubyInstaller v1.8.7 at C:/Ruby187

Initialization complete! Please review and modify the auto-generated
'config.yml' file to ensure it contains the root directories to all
of the installed Rubies you want enhanced by the DevKit.

C:\DevKit>ruby dk.rb install
[INFO] Updating convenience notice gem override for 'C:/Ruby187'
[INFO] Installing 'C:/Ruby187/lib/ruby/site_ruby/devkit.rb'

C:\DevKit>gem install rdiscount --platform=ruby
Fetching: rdiscount-1.6.8.gem (100%)
Temporarily enhancing PATH to include DevKit...
Building native extensions.  This could take a while...
Successfully installed rdiscount-1.6.8
1 gem installed
Installing ri documentation for rdiscount-1.6.8...
Installing RDoc documentation for rdiscount-1.6.8...

C:\DevKit>ruby -rubygems -e "require 'rdiscount'; puts RDiscount.new('**Hello RubyInstaller**').to_html"
<p><strong>Hello RubyInstaller</strong></p>

Install the restfully gem

Install the restfully gems using the following command:

gem install restfully --no-ri --no-rdoc

For example:

C:\DevKit>gem install restfully --no-ri --no-rdoc
Temporarily enhancing PATH to include DevKit...
Building native extensions.  This could take a while...
Fetching: mime-types-1.16.gem (100%)
Fetching: rest-client-1.6.3.gem (100%)
Fetching: rack-1.3.2.gem (100%)
Fetching: rest-client-components-1.2.0.gem (100%)
Fetching: rack-cache-1.0.2.gem (100%)
Fetching: backports-2.3.0.gem (100%)
Fetching: addressable-2.2.6.gem (100%)
Fetching: restfully-0.8.6.gem (100%)
Successfully installed json-1.5.3
Successfully installed mime-types-1.16
Successfully installed rest-client-1.6.3
Successfully installed rack-1.3.2  
Successfully installed rest-client-components-1.2.0
Successfully installed rack-cache-1.0.2
Successfully installed backports-2.3.0
Successfully installed addressable-2.2.6
Successfully installed restfully-0.8.6
9 gems installed

Install libxml-ruby

To install libxml-ruby follow the instructions at http://vairoj.com/2010/06/installing-libxml-ruby-on-windows-the-painless-way.html.

But for me the stage two command did not work so I used:

gem install libxml-ruby

rather than:

gem install libxml-ruby --platform x86-mswin32-60

and it worked fine.

Restfully should now work for you.