Hack 63 Create a SOAP 1.2 Document

W3C's SOAP provides a way to package messages or requests in XML envelopes.

SOAP is a W3C framework or protocol for the exchange of information between "peers in a decentralized, distributed environment" (http://www.w3.org/TR/soap12-part0/#L1153). SOAP is managed by the W3C's XML Protocol Working Group (http://www.w3.org/2000/xp/Group/). Originally, SOAP was an acronym for Simple Object Access Protocol, but that interpretation has been dropped.

The original SOAP attracted a lot of interest early on, but as applications of SOAP rolled out (such as the API for Google, http://www.google.com/apis/), many people complained that non-SOAP interfaces were easier to use (http://www.prescod.net/rest/googleapi/). Amazon's Web Services developer kit offers SOAP and REST (or Representational State Transfer, which is basically XML plus HTTP) interfaces, but the uptake for the REST interface seems to have been greater than for SOAP. Some prefer to avoid SOAP and commercial web services solutions altogether. Nevertheless, SOAP remains an approach at least worth examining.

Doing Business with XML

SOAP is only one attempt at packaging messages or documents for web consumption. There exists an almost overwhelming number of initiatives attempting to specify vocabularies and other technologies for doing business on the Web. This sidebar is a brief roundup of some of the efforts I hear about regularly.

Web services have taken on the task of reshaping the world, and there are a gaggle of specs being developed in the space?the Web Services Interoperability Organization or WS-I is one space (http://www.ws-i.org/) and the Web Services technical committees of OASIS is another (http://www.oasis-open.org). Web Services Description Language (WSDL) is a W3C-driven initiative for a vocabulary that describes web services concisely (http://www.w3.org/2002/ws/desc/).

ebXML is a series of OASIS-sponsored specs that are intended to enable enterprises to conduct business over the Internet (http://www.ebxml.org). Universal Description, Discovery and Integration (UDDI) is another OASIS effort to specify a platform to help find and use web services across the Internet (http://www.uddi.org/). Universal Business Language (UBL) is yet another OASIS effort aimed at creating a set of common XML vocabularies for orders, invoices, and more (http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ubl). Extensible Business Reporting Language (XBRL) is an XML-based language that describes financial information for businesses (http://www.xbrl.org/).

The main concept behind SOAP is the remote procedure call (RPC), whereby one computer on a network can send a message or command to another computer on the network. The computer that receives the call can hand such an RPC to a local program. Then, if desired, the local program can send a reply?such as a return value?back to the original machine it came from.

SOAP is much more than just an XML vocabulary, though an XML vocabulary is an important part of it. The information in a SOAP envelope can be represented in forms other than XML across the wire. SOAP has a basic data model (http://www.w3.org/TR/soap12-part2/#datamodel) that represents structures as "a directed edge-labeled graph of nodes." SOAP also has a set of optional encoding rules that may be used to encode messages that conform to the SOAP data model (http://www.w3.org/TR/soap12-part2/#soapenc). This hack will demonstrate what a SOAP envelope looks like in XML and some of the features that surround it.

Example 4-6 shows soap.xml, an XML representation of a SOAP message.

Example 4-6. soap.xml

<?xml version="1.0" encoding="UTF-8"?>

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope"> 

 <env:Header>

  <dt:instant xmlns:dt="http://www.wyeast.net/date" 

      env:role="http://www.w3.org/2003/05/soap-envelope/role/next"

      env:mustUnderstand="true">

    <dt:date year="2004" month="06" day="30"/>

  </dt:instant>

 </env:Header>

 <env:Body>

  <tz:time timezone="PST" xmlns:tz="http://www.wyeast.net/time" env:encodingStyle=

"http://www.w3.org/2003/05/soap-encoding">

   <tz:hour>11</tz:hour>

   <tz:minute>59</tz:minute>

   <tz:second>59</tz:second>

   <tz:meridiem>p.m.</tz:meridiem>

   <tz:atomic signal="true"/>

  </tz:time>

 </env:Body>

</env:Envelope>

The document element is Envelope, the container for the SOAP message. The env: prefix is the customary prefix for SOAP envelopes using the namespace http://www.w3.org/2003/05/soap-envelope. The Envelope element has two children, Header and Body. Header is optional, but Body is not. Both of these elements contain XML elements for some other namespace.

SOAP messages are expected to be sent to at least one SOAP receiver, though there may be more. SOAP intermediaries may be included along the path of a SOAP message, and each of those intermediaries is expected to have some role in processing or handling the message.

The role attribute, with the value http://www.w3.org/2003/05/soap-envelope/role/next, indicates that the application receiving the message must look over and perhaps process the message before sending it on to the next destination. The mustUnderstand attribute with a value of true means the header block that contains it must be understood by (i.e., properly handled by) the application receiving the message.

The information contained in the Body element is considered the payload of the message. The encodingStyle attribute with a value of http://www.w3.org/2003/05/soap-encoding tells the processing application that contents of structure follow SOAP's optional encoding rules.

Finally, SOAP may be transported by a variety of protocols, most prominently HTTP. For example, you can grab SOAP messages with HTTP GET (http://www.w3.org/TR/soap12-part0/#L26854) or post a message with HTTP POST (http://www.w3.org/TR/soap12-part0/#L26854). Other transportation methods for SOAP include web architectures that identify SOAP messages with URIs (http://www.w3.org/TR/soap12-part0/#L3677) and email (http://www.w3.org/TR/soap12-part0/#L26854).

4.6.1 See Also

For a more thorough introduction to SOAP, read the SOAP v1.2 primer (Part 0): http://www.w3.org/TR/soap12-part0/
SOAP v1.2 messaging framework (Part 1), including information on the SOAP processing model and message constructs: http://www.w3.org/TR/soap12-part1/
SOAP v1.2 adjuncts (Part 2), including information on the SOAP data model, encoding, and HTTP binding: http://www.w3.org/TR/soap12-part2/