Writing a SOAP Client

Table of contents:

Credit: Kevin Marshall

Problem

You need to call a remote method through a SOAP-based web service.

Solution

Use the SOAP RPC Driver in the Ruby standard library.

This simple program prints a quote of the day. It uses the SOAP RPC Driver to connect to the SOAP web service at codingtheweb.com.

	require soap/rpc/driver
	driver = SOAP::RPC::Driver.new(
	 http://webservices.codingtheweb.com/bin/qotd,
	 urn:xmethods-qotd)

Once the driver is set up, we define the web service method we want to call (getQuote). We can then call it like a normal Ruby method and display the result:

	driver.add_method(getQuote)

	puts driver.getQuote
	# The holy passion of Friendship is of so sweet and steady and
	# loyal and enduring a nature that it will last through a whole
	# lifetime, if not asked to lend money.
	# Mark Twain (1835 - 1910)

Discussion

SOAP is a heavyweight protocol for web services, a distant descendant of XML-RPC. As with XML-RPC, a SOAP client sends an XML representation of a method call to a server, and gets back an XML representation of a return value. The whole process is more complex than XML-RPC, but Rubys built-in SOAP library handles the low-level details for you, leaving you free to focus on using the results in your program.

There are only a few things you need to know to build useful SOAP clients (as I run through them, Ill build another SOAP client; this one is to get stock quotes):

The location of the web service (known as the endpoint URL) and the namespace used by the services documents.

	require soap/rpc/driver
	driver = SOAP::RPC::Driver.new(
	 http://services.xmethods.net/soap/, # The endpoint url
	 urn:xmethods-delayed-quotes) # The namespace

The name of the SOAP method you want to call, and the names of its parameters.
```
	driver.add_method(getQuote, symbol)
```
Behind the scenes, that call to add_method actually defines a new method on the SOAP::RPC::Driver object. The SOAP library uses metaprogramming to create custom Ruby methods that act like SOAP methods.
The details about the results you expect back.
```
	puts Stock price: %.2f % driver.getQuote(TR)
	# Stock price: 28.78
```
We expect the stock quote service in the example to return a floating-point value, which we simply display. With more complex result sets, youll probably assign the results to a variable, which youll treat as an array or class instance.

Problem

Solution

Discussion

See Also