Wrest

(c) Copyright 2009 Sidu Ponnappa. All Rights Reserved.

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, do sudo gem install 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.

Documentation

Wrest RDocs can be found at http://wrest.rubyforge.org/

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