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).
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
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:
<value> parameter1 </value>
<value> parameter2 </value>
.... more parameters ...
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.
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:
<value> parameter </value>
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.