Foaming SOAP

By Mark Gibbs
Network World, 03/25/02

"SOAP Version 1.2 provides the definition of an XML document which can be used for exchanging structured and typed information between peers in a decentralized, distributed environment. It is fundamentally a stateless, one-way message exchange paradigm, but applications can create more complex interaction patterns, [such as], request/response, request/multiple responses, [and others], by combining such one-way exchanges with features provided by an underlying transport protocol and/or application-specific information. . . . Also, SOAP provides a full description of the expected actions taken by a SOAP processor on receiving a SOAP message."
- W3C SOAP Version 1.2 Part 0: Primer, W3C Working Draft 17, December 2001.

So, last week on the way to explaining what Simple Object Access Protocol (SOAP) is, we beat the topic of remote procedure calls into shape because RPCs are essentially what SOAP is all about - invoking a remote process and passing its parameters and optionally receiving a response with optional data.

The key to the communication between the remote process and its client is XML. Under SOAP, an XML-formatted message is used for both endpoints - that is, client and server.

A SOAP method (the process it is being called) is uniquely identified by a namespace universal resource indicator (URI) and an NCName. The NCName maps to the symbolic name of the process being called - otherwise called the method.

SOAP method requests are HTTP post requests that have a SOAPMethodName HTTP header:

POST /objectURI HTTP/1.1
Host: www.vitallyimportantinformation.com
SOAPMethodName: urn:vii:buffet#getNumStories
Content-Type: text/xml
Content-Length: nnnn

This HTTP header indicates that the getNumStories method under the urn: vii:buffet namespace should be invoked. You can place any valid XML inside the SOAP:Body tag.

The other part of the SOAP request, the HTTP message body, is an XML document. This document contains the information needed to invoke the request.

Let's say that what we're doing is getting news items from a server named www.vitallyimportantinformation.com and what is required is the date of the news. The request would look like this:

<?xml version='1.0'?>
<SOAP:Envelope
xmlns:SOAP='urn:schemas-xmlsoap-org:soap.v1'>
<SOAP:Body>
<i:getStories
xmlns:i='urn: vii:buffet#getNumStories'>
<date>032502</date>
</i:getNumStories>
</SOAP:Body>
</SOAP:Envelope>

The architecture of the request consists of SOAP:Envelope, under which is SOAP:Body. All that is needed to invoke the getNumStories method is a date, so in this example there is only one child element below the i:getNumStories element.

After the server handles the SOAP request, the response might look something like this:

200 OK
Content-Type: text/xml
Content-Length: nnnn
<?xml version='1.0'?>
<SOAP:Envelope
xmlns:SOAP='urn:schemas-xmlsoap-org:soap.v1'>
<SOAP:Body>
<i:getNumStories
xmlns:i='urn: vii:buffet#getNumStories'>
<count>3</count>
</i:getNumStories>
</SOAP:Body>
</SOAP:Envelope>

It really is that simple. Well, OK, it's not actually simple, but unless you're going to become a programmer, that is a sound outline of the SOAP mechanism. If you want more, check out "Inside SOAP" by Don Box.