XML Reference Guide

The ultimate goal of this project is to use Perl to gather information from a web service, so we'll start with that. Amazon's Electronic Commerce System (ECS, formerly Amazon Web Services) provides both a SOAP and a REST interface, but at least for now, we'll stick with SOAP.

We've talked about SOAP, the Simple Object Access Protocol, before. It is, at heart, just XML being sent between two points, usually via HTTP, so you could use Perl to get into the nitty gritty and work with the actual messages. Fortunately, we don't have to work that hard. Instead, we can use the SOAP::Lite package, which provides a number of handy capabilities, from building SOAP messages to analyzing WSDL files to actually sending the messages.

So let's start by building the simplest of systems. For example, consider a sytem that simply takes an ISBN and returns a book title. We might have a request message of:

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2002/12/soap-envelope"> 
 <env:Header></env:Header>

<env:Body>
    <isbn:getTitle xmlns:isbn="http://www.nicholaschase.com/BookLook">0672324229</isbn:getTitle>
</env:Body>
</env:Envelope>

When we send the request to the web service, the service returns a message of:

<?xml version='1.0' ?>
<env:Envelope xmlns:env="http://www.w3.org/2002/12/soap-envelope"> 
 <env:Header></env:Header>

<env:Body>
    <isbn:getTitleResponse xmlns:isbn="http://www.nicholaschase.com/BookLook">XML Primer Plus</isbn:getTitleResponse>
</env:Body>
</env:Envelope>

So how do we make it happen? Well, first, we need a server. (Actually, first we need to start by installing SOAP::Lite and integrating it with a web server. You can get instructions on that here. I've set up a simple server at http://www.nicholaschase.com/cgi-bin/isbn.cgi, which returns the title, author, and price of a book when given the ISBN.

To set that up, we'll start by creating the server.

#!/usr/local/bin/perl 
use CGI qw/:standard :netscape/;

use SOAP::Transport::HTTP;

  SOAP::Transport::HTTP::CGI
    -> dispatch_to('BookLook')
    -> handle;

  package BookLook;

  sub getTitle {
      my ($class, $isbn) = @_;

      if ($isbn == '0672324229'){
          return "XML Primer Plus";
      } else { 
          return "Unknown";
      }
  }

  sub getAllInfo {
      my ($class, $isbn) = @_;

      if ($isbn == '0672324229'){
          return 'XML Primer Plus by Nicholas Chase, $32.58';
      } else {
          return "Unknown";
      }
  }

I've saved mine in the cgi-bin directory and called it isbn.cgi.

Now, besides the fact that I've obviously put this together a s a proof of concept (though it would, of course, be nice if everyone who ever wanted a book wanted mine), notice that there's not a drop of XML or XML-related code in this script. Instaed, we're creating a type of proxy. The dispatch_to command takes the request message and extracts the actual command, such as getTitle() or getAllInfo(), and dispatches it to the proper subroutine. It then creates the response message from the data, which it sends back to the requestor.

So now we need a client to access the service. Create another script and add the following code:

#!/usr/local/bin/perl

use SOAP::Lite;

my $lookup = SOAP::Lite->uri('http://www.nicholaschase.com/BookLook')
                       ->proxy('http://www.nicholaschase.com/cgi-bin/isbn.cgi');
print $lookup->getTitle('0672324229')->result;

Once again we're using the SOAP::Lite software to create a proxy, but this time, we're converting a command into a SOAP message. The proxy creates that message, sends it, and waits for the response. It then extracts the resulting data from that response. (Note that the uri method sets the namespace URL for the request. Here, it's the same as the package name.)

If you run this script from the command line, you should see a response something like:

>>>perl isbnclient.cgi
XML Primer Plus

Now all of that is fine, but it's rare to find a web service with such a simple interface. In most cases, you're looking at something more like this request:

<env:Envelope xmlns:env="http://www.w3.org/2002/12/soap-envelope"> 
 <env:Header></env:Header>
<env:Body>
    <isbn:findIsbn xmlns:isbn="http://www.nicholaschase.com/BookLook">
        <isbn:author>Nicholas Chase</isbn:author>

        <isbn:year>2002</isbn:year>
    </isbn:findIsbn>
</env:Body>
</env:Envelope>

or this response

<env:Envelope xmlns:env="http://www.w3.org/2002/12/soap-envelope"> 
 <env:Header></env:Header>
<env:Body>
    <isbn:getAllInfoResponse xmlns:isbn="http://www.nicholaschase.com/BookLook">
        <isbn:info>
            <isbn:title>XML Primer Plus</isbn:title>

            <isbn:author>Nicholas Chase</isbn:author>
            <isbn:price>32.58</isbn:price>
        </isbn:info>
    </isbn:getAllInfoResponse>
</env:Body>

</env:Envelope>

We can build these complex messages using the SOAP::Data object. For example, we can create the request:

...

my $lookup = SOAP::Lite->uri('http://www.nicholaschase.com/BookLook')
             ->proxy('http://www.nicholaschase.com/cgi-bin/isbn.cgi');

my $authorElement = SOAP::Data->name('author')
                              ->value('Nicholas Chase');
my $yearElement = SOAP::Data->name('year')
                            ->value('2003');

print $lookup->findIsbn($authorElement, $yearElement)->result;

Here we create the SOAP::Data object, which is essentially an XML element, and set its name and value. (Technically, we're actually creating an element node and text node child.) We can then send these elements as payload of the message, where they'll subsequently be used as the arguments of the method.

The server script accesses the data as input parameters:

...
  sub findIsbn {
      my ($class, $author, $year) = @_;

      if ($author == 'Nicholas Chase'){
          if ($year == '2002'){
             return "0672324229";
          } else {
             return "Other";
          }
      } else {
          return "Unknown";
      }
  }

The server builds a more complex response the same way:

  sub getAllInfo {
      my ($class, $isbn) = @_;

      if ($isbn == '0672324229'){
          return SOAP::Data->name('info')
                            ->value(SOAP::Data->name('title')->value('XML Primer Plus'),
                                    SOAP::Data->name(author=>'Nicholas Chase'),
                                    SOAP::Data->name(price=>'$32.58'));

      } else {
          return "Unknown";
      }
  }

(Note that the server set up by SOAP::Lite does not ordinarily return a message like the one in the previous listing, although it can. By default, the message will bear the name of the method involved. You can, however, override the Serializer to control how everything looks, but that is well beyond the scope of this discussion.)

A few things to notice here. First, that we can have an XML element as the child of another element. Second, notice the slightly different structure I used in creating the author and the price. Both of these notations are correct.

The client reads the returned obect partially as an object and partially as an XML stream, using XPath to pull specific data:

my $lookup = SOAP::Lite->uri('http://www.nicholaschase.com/BookLook')
          ->proxy('http://www.nicholaschase.com/cgi-bin/isbn.cgi');
$response = $lookup->getAllInfo('0672324229');
print "The title is " . $response->dataof('//title')->value;
print "\n";
print "The author is " . $response->dataof('//author')->value;
print "\n";
print "The price is " . $response->dataof('//price')->value;
print "\n";

We'll see more of this next, when we start dealing with actual Amazon data.