A Gentle Introduction to SOAP

Sam Ruby
It's just data

Home

Keith Ballinger

Cory Doctorow

Miguel de Icaza

Clay Shirky

Dave Winer

Axis

BlogDex

DayPop

Gump

Interop

O'Reilly

Slashdot

SOAP-ENV

SOAP::Lite

SoapBuilders

SoapDir

WSDL

WSTK

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.

Starting Simple

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.

Selecting the namespace

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?

Making namespaces explicit

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>

A more realistic message

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>

Adding a parameter

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.

Making the encoding explicit

Note: This step is no longer recommended.

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>

Making the data type explicit

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.

Conclusion

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.