Winston{yw}

Ruby comes with an implementation of SOAP (SOAP4R), a protocol for exchanging XML-based messages, and recently, I had a chance to use this library. Having no knowledge of the SOAP4R library, I conveniently consulted the Pickaxe book which was on my table, and it presented me with an excellent overview of the library.

Now, I’m going to document the two different approaches of connecting to a SOAP API which I have learned from the book, so that I don’t forget them easily. I recommend the Pickaxe book if you are interested in more detailed explanations.

Xurrency is an online currency conversion service which I am using in one of my projects and Xurrency’s API is based in SOAP. The API has several methods exposed and I’ll only be using one of them in my examples, but the principle is the same for other method invocations.

The method that I’ll be using is: float getValue(float $amount, string $base, string target) which returns a float value for a currency conversion.

First Example

#Require The Library
require 'soap/rpc/driver'

#Connections
endpoint = 'http://www.xurrency.com/servidor_soap.php'
proxy    = SOAP::RPC::Driver.new(endpoint)

#Add Method
proxy.add_method('getValue', 'amount', 'base', 'target')

#Call API Method and Get Exchange Rate
rate = proxy.getValue('1','usd','eur')
puts 'Rate: #{rate}'

The output:

sh> ruby currency.rb
Rate: 0.6787

Second Example

#Require The Library
require 'soap/wsdlDriver'

#Connections
wsdl_url = 'http://xurrency.com/api.wsdl'
proxy    = SOAP::WSDLDriverFactory.new(wsdl_url).create_rpc_driver

#Call API Method and Get Exchange Rate
rate = proxy.getValue(1,'usd','eur')
puts 'Rate: #{rate}'

The output:

sh> ruby currency.rb
Rate: 0.6787

In the first example, I created a local proxy for the Xurrency API, adds the method which I want to use, and then invokes it.

In the second example, I made use of a WSDL (Web Services Description Language) document available at http://xurrency.com/api.wsdl. This WSDL document describes the Xurrency API, and so SOAP can read this WSDL and perform dynamic discovery of the API interfaces which removes the need to add the getValue method explicitly.

To quote from the Pickaxe book, a WSDL document is:

..an XML document that describes the types, methods, and access mechanisms for a Web services interface. SOAP clients can read WSDL file to create the interfaces to a server automatically..

Despite the differences when connecting to the SOAP API, the underlying concept is similar for both the examples. The SOAP library creates local proxies that SOAP uses to connect to the remote server API (which is published by a SOAP server). When a method is invoked on the local proxy, the invocation is passed to the corresponding API interface on the server via XML. The server then processes the method invocation, and the returned values are passed back to the client through the proxy.

What I have written are just some basic concepts of using SOAP with Ruby. But it’s really simple right? For further reading, please refer to the RubyDoc, or the Trac (which has some great examples too).

For a rubygem that wraps Xurrency’s API, there’s one on GitHub, authored by Keita. Alternatively, my colleague Douglas has also created a simple currency converter which uses the data from Yahoo Finance.

For those who are on Windows, but yet wish to install Ruby Thin Server on your PC, here’s a short how-to.

Ruby Thin Server requires the following dependencies:

• Rack
• EventMachine

Unfortunately, the latest version of EventMachine (0.10.0 at the time of this post) is not a Win32 binary release, so it’s a hassle trying to get it installed on Windows. Instead, your best choice would be to download an earlier version of EventMachine 0.8.1, which is a Win32 binary release.

Even though it’s an earlier version, I have not encountered any problems with it. Of course, I am using Windows only for development purposes, and not for production purposes.

Install each dependency by following the steps below before you install Thin.

1. Install Rack.

c:\> gem install rack

2. Download EventMachine 0.8.1

Download. Install EventMachine locally.
c:\> gem install eventmachine -l

3. Install Ruby Thin Server, but ignore dependencies.

c:\> gem install thin –ignore-dependencies

Following these steps should install Ruby Thin Server successfully on your Windows machine.

Update from Google Groups:
Thin has been updated to install EventMachine 0.8.1 if you are on Windows. But you can always rely on the steps above if something fails.