Wrest

© 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 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: www.assembla.com/spaces/wrest/tickets

Licence

Wrest is released under the Apache 2.0 licence