A Gentle Introduction to SOAP
By Sam Ruby, March 16, 2002.
This document provides an introduction to the SOAP protocol. Only a basic knowledge of what a procedure call is and some familiarity with XML is required.
Lets take a look at a very simple SOAP message.
<Envelope
xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<helloWorld/>
</Body>
</Envelope>
Note the use of the xmlsoap namespace. This identifies the Envelope as a SOAP Envelope. The Envelope has one Body. The body has one element.
The above, while simple, has a bug in it. The hello world element is in the default namespace, which in this case is the SOAP Envelope. Let's make the simplest fix possible to correct this:
<Envelope
xmlns="http://schemas.xmlsoap.org/soap/envelope/">
<Body>
<helloWorld xmlns="http://www.soapware.org/"/>
</Body>
</Envelope>
Namespaces merely allow one to specify which helloWorld procedure is desired. For background on why this is important, see What Object does SOAP Access?
The following is just a style issue - it does not change the meaning of the message, but most SOAP messages you see chose not to make the envelope the default namespace but rather prefer to explicitly qualify it. The resulting message looks like this:
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP:Body>
<m:helloWorld xmlns:m="http://www.soapware.org/"/>
</SOAP:Body>
</SOAP:Envelope>
Now lets change the name of the procedure, and add an argument. This procedure chosen for this example is the same one that is used in the BDG.
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP:Body>
<m:getStateName xmlns:m="http://www.soapware.org/">
<statenum>41</statenum>
</m:getStateName>
</SOAP:Body>
</SOAP:Envelope>
Suppose we wanted to support an option to indicate a preference for a state abbreviation instead. Servers that don't implement this but follow the rule that "The server must ignore all elements that it doesn't understand." will continue to accept this message.
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP:Body>
<m:getStateName xmlns:m="http://www.soapware.org/">
<statenum>41</statenum>
<format>abbreviation</format>
</m:getStateName>
</SOAP:Body>
</SOAP:Envelope>
More information on designing interfaces so that they are not brittle can be found in Coping with Change. Now that the point was made, the format parameter will be dropped from the remaining examples.
What we have actually done to this point is actually send an XML document. Since our intent is to encode a remote procedure call it may be helpful to clue the recipient in on this fact up front.
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP:Body>
<m:getStateName xmlns:m="http://www.soapware.org/">
<statenum>41</statenum>
</m:getStateName>
</SOAP:Body>
</SOAP:Envelope>
Now lets declare the statenum as a 32 bit integer:
<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/"
SOAP:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP:Body>
<m:getStateName xmlns:m="http://www.soapware.org/">
<statenum xsi:type="xsd:int">41</statenum>
</m:getStateName>
</SOAP:Body>
</SOAP:Envelope>
In many cases, such an addition is not necessary or appropriate. Perhaps the data type could be predetermined and captured in a document such as a WSDL. Alternatively, the data type could be dynamically determined by the recipient. But for the cases where adding the data type is appropriate, the above demonstrates how it is done.
This essay just scratched the surface. It did not show how requests are transmitted over HTTP, nor did it cover responses or faults. These topics are covered in the Busy Developer's Guide to SOAP 1.1.