Home

Who are we

Articles

SOAP - A Quick Intro to Webservices

XML-RPC - A Five-Minute Tutorial

Installing Apache2 and mod_perl (Windows XP)

Links

XML-RPC - A Five-Minute Tutorial

You want (or need) to get started with web services. Maybe your boss read about it and wants to join the fun, not to look outdated. After all it's said to be the greatest thing since the introduction of the world wide web. You start looking around on the web for information. Or you stop by your local bookstore and start browsing through the long list of books on this subject. It's got to do with XML, so much you know. 'No problem', you think, 'that's cool. I kind of now what that's about.' Then you read about SOAP... and WSDL... and UDDI. 'Well' - you think, 'I'm usually best when learning by doing'. So you pull out some quick start guide (typically in Java), type in some code, build the code with the provided build tool, use the provided deploy tool to deploy the service on the server you just downloaded and installed (tomcat?) and if you're lucky enough it actually runs. You have a web service - a server that can talk to a client. But when you think about it - you have no idea what you just did and even more, how to do the same with your own applications. So what now? Maybe get a beer instead...

Well, maybe you're lucky and you don't feel that way. But I know I was in exactly the situation I described above. The more I looked into this, the more confusing it got. One of the problems I found was that Java, as useful as it otherwise may be, is not necessarily the language to learn web services. This is not a problem with the language itself, but rather with the implementation of servers and clients combined with the concept of Java servlets that takes too much emphasis away from the underlying concept, which is not that difficult. So I would like to take a little different path in this article, which is planned to be the first on a general introduction to web services.

To get started with web services, as with anyting else, it is often useful to start the easiest possible scenario. In this case it is XML-RPC - one could maybe call it remote procedure calls (RPC) using a 'SOAP-very-light'. What does that mean? A RPC is nothing else than calling a function (or method), but instead of this function being included into the program itself, it resides on a server or communicates over a server. Looking at the situation this way may illustrate one of the reasons web services are so interesting. Instead of writing a piece of code to provide certain services and then reuse this in every application that needs it, one could implement the service once as a web service and then use it in every application that needs that service. Furthermore, since web services use an open standard they are not bound to any particular technology and as such the same service can be used by a C# developer just as well as by a Java developer.

So, web service implementations need a server that provides a service and clients that requests it. The XML in 'XML-RPC' represents the format used to encode the information exchanged between these two. And finally, HTTP is the protocol used to make server and client 'talk' to each other. (This illustrates btw pretty nicely that 'talking' alone does not imply actually information exchange).

The full specification of XML-RPC can be found at www.xmlrpc.com/spec. If you follow the link and look at it you will be surprised how ridiculously short it is. And, yes, that's all there is to it. But nevertheless I will summarize it here in short (please refer to the link above for more details).

Some Theory - XML-RPC Specs

Requests

A client request is made up by a header and the data. You typically don't have to care too much about the header - since we're using HTTP, it's pretty much a standard HTTP header as used for communication between web servers and browsers. I'll skip this part. The data (payload) is the interesting part. It is just an xml document made up like this:

 
<?xml version="1.0"?>
<methodCall>
   <methodName>examples.getStateName</methodName>
   <params>
      <param>
         <value> parameter1 </value>
      </param>
      <param>
         <value> parameter2 </value>
      </param>
       .... more parameters ...
      </params>
</methodCall>

The remote procedure call parameters, like parameter1 have to be one of the eight defined types:

There are six basic types:

  • <int> or <i4> - integer.
  • <double> - a double precision.
  • <string> - string, the default type if no type is defined.
  • <boolean> - 0 or 1.
  • <dateTime.iso8601> data/time format.
  • <base64> - base64-encoded binary, basically a blob.

And two 'container' types:

  • <array> - an array or list type.
  • <struct> - a hash, i.e. a set of key/value pairs.

There is no restriction to the number of parameters in a request - it can range from 0 to whatever you feel like cramming into a request.

Response

Again I'll skip the header. Please refer to the specifications for details on the HTTP return code etc. What the data is concerned exactly one value is returned. Otherwise it looks pretty much like the request:

 
<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value> parameter </value>
      </param>
   </params>
</methodResponse>

At first it sounds somewhat limiting that only one value can be returned. But actually, that's not different from normal method calls and the way around this limitation of course is to use an <array> or <struct>. In case of an error the server response can look differently and contain a <fault>. Please refer to the specs page for details.