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.