Wrest

Wrest is a ruby REST client library which allows you to quickly build object oriented wrappers around any web service. It has two components - Wrest Core and Wrest::Resource.

Installation

The source is available at git://github.com/kaiwren/wrest.git

To install as a Rails plugin, do script/plugin install git://github.com/kaiwren/wrest.git

To install the Wrest gem, you'll need to add GitHub to you gem sources if you haven't already done so:

gem sources -a http://gems.github.com

Then to install Wrest and its dependencies:

sudo gem install kaiwren-wrest

Wrest Core

Designed to be used as a library, not just a command line REST client
Provides basic infrastructure (including an interactive shell) and convenient HTTP wrappers
Makes it easy to extend and modify both serialisation, deserialisation and object creation
Isn't coupled to Rails (usable in a pure Ruby application to consume any REST api)
Can be used both stand alone as well as to build object oriented abstractions around web services (Wrest::Resource is an example of the latter)

Usage: Shell

You can launch the interactive Wrest shell by running bin/wrest if you have the source or invoking wrest from your prompt if you've installed the gem. $ wrest

"http://search.yahooapis.com/NewsSearchService/V1/newsSearch?appid=YahooDemo&output=json&query=India&results=3&start=1".to_uri.get

Usage: Library

require 'rubygems'
require 'wrest'
y "http://search.yahooapis.com/NewsSearchService/V1/newsSearch".to_uri.get(
								:appid  => 'YahooDemo', 
								:output => 'xml',
								:query  => 'India',
								:results=> '3',
								:start  => '1'
							)

Basic Http Calls

Get

A couple of ways to get the Yahoo news as hash map (needs the JSON gem - gem install json).

This example simply does a get on a uri and figures out the appropriate deserialiser using the content-type (in this case 'text/javascript', which uses Wrest::Translators::Json). See content_types.rb under lib/wrest/mappers/translators. "http://search.yahooapis.com/NewsSearchService/V1/newsSearch?appid=YahooDemo&output=json&query=India&results=3&start=1".to_uri.get.deserialise
This example does a get on a base uri with several parameters passed to it, resulting in a uri essentially the same as the one above. It also shows how you can use a custom deserialiser to produce a hash-map from the response. "http://search.yahooapis.com/NewsSearchService/V1/newsSearch".to_uri.get( :appid => 'YahooDemo', :output => 'xml', :query => 'India', :results=> '3', :start => '1' ).deserialise_using(Wrest::Translators::Xml)

Logging

The Wrest logger can be set and accessed through Wrest.logger and is configured by default to log to STDOUT. If you're using Wrest in a Rails application, you can configure logging by placing the following line in your environment file:

Wrest.logger = ActiveRecord::Base.logger

Build

Standard options are available and can be listed using rake -T. Use rake:rcov for coverage and rake:rdoc to generate documentation.

Wrest::Resource

Wrest::Resource is an alternative to ActiveResource which targets Rails REST services; it is currently under development.

Out of the box support for collections
Out of the box support for collection pagination (including support for WillPaginate), both header based and xml attribute based
Out of the box support for operations on all the records on the collection
Out of the box support for nested resources
Out of the box support for cached resources
Out of the box support for type-casting data that comes in as parameter strings
More natural mapping of deserialised entities to existing classes
No communication via exceptions for http error status codes
Better extensibility - allows access to request/response objects, avoids class variables, favours symbols over strings etc.

Dependencies

gems
xmlsimple
json
rspec
rcov
active_support

Support

This project uses Assembla for ticketing: http://www.assembla.com/spaces/wrest/tickets

Licence

Wrest is released under the Apache 2.0 licence