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.

Since no single framework can provide an object oriented wrapper suitable for all available web services, it follows that Wrest should focus on providing you with the tools to help you roll your own with ease. Wrest::Resource is an example of this - an object oriented wrapper for the kind of REST APIs exposed by Rails applications built using Wrest Core.

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 is also available as a gem for JRuby using the same command.

Wrest Core

  • Designed to be used as a library, not just a command line REST client

  • Provides infrastructure components such as convenient HTTP wrappers api, caching, redirect handling, serialisation, deserialisation etc.

  • 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 specify a custom deserialiser to produce a hash-map from the response, as well as a hash mutator to clean up the deserialised hash. require ‘rubygems’ require ‘wrest’

    include Wrest::Components p “search.yahooapis.com/NewsSearchService/V1/newsSearch”.to_uri.get(

:appid => ‘YahooDemo’, :output => ‘xml’, :query => ‘India’, :results=> ‘3’, :start => ‘1’ ).deserialise_using( Translators::Xml ).mutate_using( Mutators::XmlSimpleTypeCaster.new )

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. It targets Rails REST services and is currently under development.

  • No more pretending that REST resources are the same as database records

  • 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

Source

  • gems

  • xmlsimple

  • json (json-jruby on JRuby)

  • active_support

Build

  • rspec

  • rcov (unsupported on JRuby)

  • jeweler

Support

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

Licence

Wrest is released under the Apache 2.0 licence