Update: Please let me know if the <pre> tags bother you. I wrote this in pod. I'll try and convert it to code tags if you think it's necessary.

SOAP

(Simple Object Access Protocol : http://www.w3.org/TR/SOAP/)

SOAP is a lightweight protocol for exchanging data using XML. It allows you access methods and properties of remote objects. Each method call is typically a seperate SOAP envelope (xml document). The SOAP server opens the envelope, processes the data, and returns an envelope to the client with a response.

SOAP::Lite does the hard work (creating the envelopes and decoding them), leaving the developer the easy task or writing client and server code which is almost no different to what she would have written before.

Why use SOAP::Lite

* It's much easier that using SOAP where you have to do a lot of the hard work as well

* It supports SOAP 1.1

* It supports lots of protocols other than HTTP. You can even create your own SOAP daemon

* It supports WSDL (Web Service Description Language)

* It supports tracing - so you can see what's going on behind the scenes

* You can use the COM interface on Windows machines

* It's very well documented

Why NOT use SOAP::Lite

* You want a more low-level API - and more work

* SOAP can be slower that methods you may already be using

* You prefer shower gel

Simple Calculator SOAP Server

The SOAP server is a regular Perl script, which instructs SOAP::Lite to dispatch methods to a named package. My example uses SOAP::Lite's CGI implimentation, but you can use SOAP::Lite over many other protocols such as POP3, SMTP and FTP.

  use strict;
  use SOAP::Transport::HTTP;
  SOAP::Transport::HTTP::CGI   
    -> dispatch_to('My::SoapServer')
    -> handle;

  package My::SoapServer;

  sub add      { $_[1] + $_[2]; }
  sub subtract { $_[1] - $_[2]; }
  sub multiply { $_[1] * $_[2]; }
  sub divide   { $_[1] / $_[2]; }

Note that I am ignoring the first parameter for each of the method calls since it is simply the package name. I guess that SOAP::Lite interprets your requests as (in this case): My::SoapServer->methodname.

Client Code to access this Web Service

The client code is quite straightforward. You create a SOAP::lite object, passing it the details on the SOAP service. Then for each method call, it returns an object which has, amongst others, result and fault methods.

  use strict;
  use SOAP::Lite;
  my $soap = SOAP::Lite
    ->uri("http://myserver.org/My::SoapServer")
    ->proxy("http://www.mywebserver.com/soapserver.pl");

  print $soap->add(16,8)->result,       "\n";
  print $soap->subtract(10,2)->result,  "\n";
  print $soap->multiply(5,5)->result,   "\n";
  print $soap->divide(1024,2)->result,  "\n";

Catching Errors

Suppose I misspell the method call (ADD instead of add):

  print $soap->ADD(16,8)->result;

...prints nothing. Not very helpful. However, if you do the following, you can print the fault, (if there is one)...

  my $res = $soap->ADD(16,10);
  if ($res->fault) {
    print $res->faultstring;
  } else {
    print $res->result;
  }

And this time, it will print ``Bad Method Call''

There are many more error handling functions provided by SOAP::Lite. But you'll need to read the documentation!

Autodispatching

So far, the client code all looks a bit un-friendly. SOAP::Lite has a feature called autodispatch which allows you to write your client code just the same way you would write it if My::SoapServer were a locally installed module. e.g.

  print add(100,-99);

See the SOAP::Lite docs for more information and unexpected side-effects.

Things to note

See the documentation on autodispatch before you use it - or it might have strange side-efects. (It overloads UNIVERSAL::AUTOLOAD)

See the documentation on performance - you may be able to improve performance by base64 encoding the XML;

Useful Links

There is a two part article on perl.com by Paul Kulchenko (SOAP::Lite author):

Part 1: http://www.perl.com/pub/2001/01/soap.html
Part 2: http://www.perl.com/pub/2001/04/24/soap.html

and you can visit Paul's site at the aptly named http://www.soaplite.com, which is an excellent SOAP resource in itself

Update 2: http://www.salcentral.com and http://www.xmethods.net both provide listings of Web Services you can play around with.