In this sample book chapter from Essential XML Quick Reference: A Programmer's Reference to XML, XPath, XSLT, XML Schema, SOAP, and More, you'll learn the basics of SOAP and how to put it to w
The Simple Object Access Protocol (SOAP) is an XML messaging specification that describes a message format along with a set of serialization rules for datatypes including structured types and arrays. In addition, it describes how to use the Hypertext Transfer Protocol (HTTP) as a transport for such messages. SOAP messages are effectively service requests sent to some end point on a network. That end point may be implemented in any number of ways—Remote
Protocol Call (RPC) server, Component Object Model (COM) object, Java servlet, Perl script—and may be running on any platform. Thus, SOAP is about interoperability between applications running on potentially disparate platforms using various implementation technologies in various programming languages.
10.1 Introduction to SOAP messages
SOAP messages are transmitted between applications and may pass through a number of intermediaries as they travel from the initial sender to the ultimate recipient. SOAP messages are comprised of an Envelope element, with an optional Header and a mandatory Body child element. All three elements are in the namespace http://schemas.xmlsoap.org/soap/envelope/. The Envelope identifies the XML as being a SOAP message and must be the root element of the message. The Body element contains the message payload. The Header element provides an extension hook that allows SOAP to be extended in arbitrary ways. The following sections describe these elements, attributes that
SOAP defines, the data encoding rules SOAP specifies, and the HTTP binding.
Example: Skeleton SOAP message
<soap:Envelope
xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'
soap:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
<soap:Header>
<!-- extensions go here -->
</soap:Header>
<soap:Body>
<!-- message payload goes here -->
</soap:Body>
</soap:Envelope>
10.2 Elements in SOAP messages
ADVERTISEMENT
SOAP defines four elements in the namespace http://schemas.xmlsoap.org/soap/envelope/. These elements are listed in the following sections in alphabetical order, with a description and details of child elements. All four elements can be annotated with any number of namespace-qualified attributes. Example SOAP request and response messages are shown for reference.
10.2.1 Body
<soap:Body
xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/' >
<!-- message payload goes here -->
</soap:Body>
The Body element contains the message payload. In the case of a request message the payload of the message is processed by the receiver of the message and is typically a request to perform some service and, optionally, to return some results. In the case of a response message the payload is typically the results of some previous request or a fault.
<soap:Fault
xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'
>
<!-- detail goes here -->
</soap:Fault>
The Fault element indicates that an error occurred while processing a SOAP request. This element only appears in response messages.
Child elements
A faultcode element followed by a faultstring element followed by an optional faultactor element and an optional detail element. Each of these children is described in the following:
Name
Syntax
Description
faultcode
<faultcode xmlns=''>
QName</faultcode>
The faultcode element is of type QName and indicates what
fault occurred. Several existing categories of fault code are defined, all in
the
http://schemas.xmlsoap.org/soap/envelope/
namespace.
VersionMismatch indicates that the recipient of a message did not recognize the namespace name of the Envelope element. MustUnderstand indicates that the recipient of an element child of the Header element had a soap:mustUnderstand attribute but that element was not understood by the recipient. Client indicates the SOAP message did not contain all the required information in order for the recipient to process it. This could mean that something was missing from inside the Body element. Equally, an expected extension inside the Header element could have been missing. In either case, the sender should not resend the message without correcting the problem. Server indicates that the recipient of the message was unable to process the message because of some server-side problem. The message contents were not at fault; rather, some resource was unavailable or some processing logic failed for a reason other than an error in the message. The sender may legitimately resend the message at a later time. All these fault codes may be followed by a period and a further string providing more detailed information about the error; for example,
Client.InvalidParameter.
faultstring
<faultstring xmlns=''>
string </faultstring>
The faultstring element is of type string and provides a
human-readable description of whatever fault occurred.
faultactor
<faultactor xmlns=''>
uriReference </faultactor>
The faultactor element is of type uriReference and indicates
the source of the fault. This may be the ultimate recipient of the request
message, in which case the element is optional. Alternatively, the source of the
fault may be an intermediary somewhere in the path the message took to get from
the sender to the ultimate recipient. In this case the element must be present.
detail
<detail xmlns=''> any number of elements in
any namespace </detail>
The detail element is used to carry application-specific error information and may be annotated with any number of attributes from any namespace, and may have any number of namespace-qualified element children. The detail element must be present if the fault is the result of the recipient being unable to process the Body element. The detail element is not used to provide error information in the case of the recipient being unable to process an
element child of the Header element. In such cases, error information is placed
inside the Header element.
An example of a fault in which the request message contained an invalid
operation request
10.2.4 Header
<soap:Header
xmlns:soap='http://schemas.xmlsoap.org/soap/envelope/'
>
<!-- extensions go here -->
</soap:Header>
The Header element namespace serves as a container for extensions to SOAP. No extensions are defined by the specification, but user-defined extension services such as transaction support, locale information, authentication, digital signatures, and so forth could all be implemented by placing some information inside the Header element. Children of the Header element may be annotated with the mustUnderstand and/or actor attributes.
An example extension for locale information requesting that the recipient of the message send any responses localized for the specified locale; in this case, UK English.
