Copyright © 2002 W3C® (MIT, INRIA, Keio), All Rights Reserved. W3C liability, trademark, document use, and software licensing rules apply.
SOAP Version 1.2 Part 0: Primer is a non-normative document intended to provide an easily understandable tutorial on the features of the SOAP Version 1.2 specifications. In particular, it describes the features through various usage scenarios, and is intended to complement the normative text contained in Part 1 and Part 2 of the SOAP 1.2 specifications.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.
This is the W3C Last Call Working Draft of the SOAP Version 1.2 Part 0: Primer for review by W3C members and other interested parties. It has been produced by the XML Protocol Working Group (WG), which is part of the Web Services Activity.
Following completion of Last Call, the XML Protocol Working Group has agreed to advance the specification according to four exit criteria:
A list of open Last Call issues against this document can be found at http://www.w3.org/2000/xp/Group/xmlp-lc-issues.
Comments on this document should be sent to xmlp-comments@w3.org (public archives). It is inappropriate to send discussion emails to this address. Comments should be sent during the last call review period, which ends on 19 July 2002.
Discussion of this document takes place on the public <xml-dist-app@w3.org> mailing list (Archives) per the email communication rules in the XML Protocol Working Group Charter.
Patent disclosures relevant to this specification may be found on the Working Group's patent disclosure page.
This is a public W3C Working Draft. It is a draft document and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use W3C Working Drafts as reference material or to cite them as other than "work in progress". A list of all W3C technical reports can be found at http://www.w3.org/TR/.
SOAP Version 1.2 Part 0: Primer is a non-normative document intended to provide an easily understandable tutorial on the features of the SOAP Version 1.2 specifications [1, 2]. Its purpose is to help a technically competent person understand how SOAP may be used, by describing representative SOAP message structures and message exchange patterns.
In particular, this primer describes the features of SOAP through various usage scenarios, and is intended to complement the normative text contained in SOAP Version 1.2 Part 1: Messaging Framework (hereafter Part 1) and SOAP Version 1.2 Part 2: Adjuncts (hereafter Part 2) of the SOAP version 1.2 specifications.
It is expected that the reader has some familiarity with the basic syntax of XML, including the use of XML namespaces and infosets, and Web concepts such as URIs and HTTP. It is intended primarily for users of SOAP, such as application designers, rather than implementors of the SOAP specifications, although the latter may derive some benefit. In any case, there is no substitute for the main specifications for a fuller understanding of SOAP. To that end, this primer provides extensive links to the main specifications wherever new concepts are introduced or used.
Part 1 of the SOAP 1.2 specifications defines the SOAP envelope, which is a construct that defines an overall framework for representing the contents of a SOAP message, identifying who should deal with all or part of it, and whether handling such parts are optional or mandatory. It also defines a protocol binding framework, which describes how specifications of a binding of SOAP onto another underlying protocol may be written.
Part 2 of the SOAP 1.2 specification defines a data model for SOAP, a particular encoding scheme for data types which may be used for conveying remote procedure calls (RPC), as well as one concrete realization of the binding framework defined in Part 1. This allows the exchange of SOAP messages either as payload of a HTTP POST request and response, or as a SOAP message in the response to a HTTP GET. It offers recommendations on how RPCs, particularly those representing pure information retrieval, may be invoked in a manner which is considered "Web-friendly".
This document (the primer) is not normative, which means that it does not provide the definitive specification of SOAP 1.2. The examples provided here are intended to complement the formal specifications, and in any question of interpretation the formal specifications naturally take precedence. The examples shown here provide a subset of the uses expected for SOAP. In actual usage scenarios, SOAP will most likely be a part of an overall solution, and there may be other application-specific requirements which are not captured in these examples.
SOAP version 1.2 provides the definition of the XML-based information which can be used for exchanging structured and typed information between peers in a decentralized, distributed environment. Part 1 explains that a SOAP message is formally specified as an XML Infoset [12], which provides an abstract description of its contents. Infosets can have different on-the-wire representations, one common example of which is as an XML 1.0 document. SOAP is fundamentally a stateless, one-way message exchange paradigm, but applications can create more complex interaction patterns (e.g., request/response, request/multiple responses, etc.) by combining such one-way exchanges with features provided by an underlying protocol and/or application-specific information. SOAP is silent on the semantics of any application-specific data it conveys, as it is on issues such as the routing of SOAP messages, reliable data transfer, firewall traversal, etc. However, SOAP provides the framework by which application-specific information may be conveyed in an extensible manner. Also, SOAP provides a full description of the required actions taken by a SOAP processor on receiving a SOAP message.
Section 2 provides an introduction to the basic features of SOAP via the simplest usage scenarios, namely a one-way SOAP message, followed by various request-response type exchanges, including RPCs. Fault situations are also described, as well as the SOAP processing model.
Section 3 describes the ways in which SOAP messages may be transported to realise various usage scenarios. It describes the SOAP HTTP binding specified in Part 2, as well as an example of how SOAP messages may be conveyed in email messages. As a part of the HTTP binding, it introduces two message exchange patterns which are available to an application, one of which uses the HTTP POST method while the other uses HTTP GET. Examples are also provided on how RPCs, in particular those that represent pure information retrieval, may be represented in SOAP message exchanges in a manner that is compatible with the architectural principles of the World Wide Web .
Section 4 provides a treatment of various aspects of SOAP that can be used in more complex usage scenarios. These include the use of header elements as an extensibility mechanism which may be targeted at specific intermediate SOAP nodes to provide value-added services to communicating applications, and using various encoding schemes to serialize SOAP and application-specific data.
Section 5 describes the changes from SOAP version 1.1 [11].
Section 6 provides references.
For ease of reference, terms and concepts used in this Primer are hyper-linked to their definition in the main specifications.
Throughout this primer, sample SOAP envelopes and messages are shown as XML 1.0 documents. Part 1 explains that SOAP messages are formally specified as XML Infosets [12], which is an abstract description of their contents. The distinction between the SOAP XML Infosets and the corresponding XML documents is unlikely to be of interest to those using this primer as an introduction to SOAP; those who do care (typically those who port SOAP to new protocol bindings where the messages may have alternative representations) should understand these examples as referring to the corresponding XML Infosets. Further elaboration of this point is provided in Section 3 of this document.
The namespace prefixes "env" and "enc" used in the prose sections of this document are associated with the SOAP namespace names "http://www.w3.org/2002/06/soap-envelope" and "http://www.w3.org/2002/06/soap-encoding" respectively.
The namespace prefixes "xs" and "xsi" used in the prose sections of this document are associated with the namespace names "http://www.w3.org/2001/XMLSchema" and "http://www.w3.org/2001/XMLSchema-instance" respectively, both of which are defined in the XML Schemas specification [7, 8].
Note that the choice of any other namespace prefix is arbitrary and not semantically significant.
Namespace URIs of the general form "http://example.org/..." and "http://example.com/..." represent an application-dependent or context-dependent URI [3].
A SOAP message is fundamentally a one-way transmission between SOAP nodes, from a SOAP sender to a SOAP receiver, but SOAP messages are expected to be combined by applications to implement more complex interaction patterns ranging from request/response to multiple, back-and-forth "conversational" exchanges.
We start by exposing the structure of a SOAP message, and its exchange in some simple usage scenarios based on a travel reservation application. Various aspects of this application scenario will be used throughout the primer. In this application, an employee of a company negotiates a travel reservation with a travel booking service for a planned trip. The information exchanged between the traveller and the travel service is in the form of SOAP messages. The ultimate recipient of a SOAP message sent from the traveler's application is the travel booking service, but it is possible that the SOAP message may be "routed" through one or more SOAP intermediaries which act in some way on the message. Some simple examples of such SOAP intermediaries might be ones that log, audit or, possibly, amend each travel request.
In section 2.1, we describe a travel reservation request expressed as a SOAP message, which offers the opportunity to describe the various "parts" of a SOAP message.
In section 2.2.1 we return to our example to show a response from the travel service in the form of another SOAP message, which forms a part of a conversational message exchange as the various choices meeting the constraints of the travel request are negotiated.
In section 2.2.2, we assume that the various parameters of the travel reservation have been accepted by the traveller, and an exchange - modelled as a remote procedure call (RPC) - between the traveler and the travel service confirms various aspects of the reservation.
Section 2.3 shows examples of fault handling.
Having established the syntactical aspects of a SOAP message as well as the basic message exchange patterns, we provide in section 2.4 an overview of the SOAP processing model.
Examples and a more detailed discussion of the behaviour and role of SOAP intermediaries is postponed to section 4.
Example 1 shows data for a travel reservation expressed in a SOAP message.
<?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"> <env:Header> <m:reservation xmlns:m="http://travelcompany.example.org/reservation" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference> <m:dateAndTime>2001-11-29T13:20:00.000-05:00</m:dateAndTime> </m:reservation> <n:passenger xmlns:n="http://mycompany.example.com/employees" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <n:name>John Q. Public</n:name> </n:passenger> </env:Header> <env:Body> <p:itinerary xmlns:p="http://travelcompany.example.org/reservation/travel"> <p:departure> <p:departing>New York</p:departing> <p:arriving>Los Angeles</p:arriving> <p:departureDate>2001-12-14</p:departureDate> <p:departureTime>late afternoon</p:departureTime> <p:seatPreference>aisle</p:seatPreference> </p:departure> <p:return> <p:departing>Los Angeles</p:departing> <p:arriving>New York</p:arriving> <p:departureDate>2001-12-20</p:departureDate> <p:departureTime>mid-morning</p:departureTime> <p:seatPreference/> </p:return> </p:itinerary> <q:lodging xmlns:q="http://travelcompany.example.org/reservation/hotels"> <q:preference>none</q:preference> </q:lodging> </env:Body> </env:Envelope>
The SOAP message contains two SOAP-specific sub-elements within the
overall Envelope
, namely a Header
and a
Body
. The contents of these elements are application defined and
not a part of the SOAP specifications, although the latter do have something
to say about how such elements must be handled.
A SOAP header element is optional, but we have chosen to include it in our example. SOAP headers have been designed in anticipation of various uses for SOAP, many of which will involve the participation of other SOAP processing nodes - called SOAP intermediaries - along a message's path from a sender to an ultimate receiver, to allow SOAP nodes to exchange information to provide value-added services. These form the mechanism by which SOAP messages may be extended in an application-specific manner. (It should be kept in mind though that the SOAP specifications do not deal with how SOAP messages are routed between nodes, the manner by which the route is determined and so forth. These are a part of the overall application, and could be the subject of other specifications.)
The immediate child elements of a Header
element are called
header blocks, and represent a logical grouping of data which, as we
shall see, can individually be targeted at SOAP intermediaries encountered in
the path of a message from a sender to an ultimate receiver.
The
SOAP Body
is the mandatory element within an Envelope, which
implies that this is where the main end-to-end information conveyed in a SOAP
message must be carried.
A pictorial representation of the SOAP message in Example 1 is as follows.
In Example 1, the header contains two header
blocks, each of which is defined in its own namespace and which represent
some aspect pertaining to the overall processing of the body of the SOAP
message. For this travel reservation application, such "meta" information
pertaining to the overall request is a reservation
header block
which provides a reference and time stamp for this instance of a reservation,
and the traveller's identity in the passenger
block.
The header blocks reservation
and passenger
must
be processed by the next SOAP intermediary encountered in the message path
or, if there is no intermediary, by the ultimate recipient of the message.
The fact that it is targeted at the next SOAP node encountered en route is
indicated by the presence of the attribute role
with the value
"http://www.w3.org/2002/06/soap-envelope/role/next" (hereafter simply
"next"), which is a
role that all SOAP nodes must be willing to play. The presence of a
mustUnderstand
attribute with value "true" indicates that the
node(s) processing the header must absolutely process these header blocks in
a manner consistent with their specifications, or else not process the
message at all and throw a fault. Note that whenever a header block is
processed, either because it is marked mustUnderstand
="true" or
for another reason, the block must be processed in accordance with the
specifications for that block. Such header block specifications are
application defined and not a part of SOAP.
The choice of what data is placed in a header block and what goes in the SOAP body are decisions taken at the time of application design. The main point to keep in mind is that header blocks may be targetted at various nodes that might be encountered along a message's path from a sender to the ultimate recipient. Such intermediate SOAP nodes may provide value-added services based on data in such headers. In Example 1, the passenger data is placed in a header block because in our design we might wish to use this data at a SOAP intermediary to do some additional processing - for example, as shown later in Section 4.1, the outgoing message is altered by the SOAP intermediary by having the travel policies pertaining to this passenger appended to the message as another header block.
The Body
element and its associated child elements,
itinerary
and lodging
, are intended for exchange of
information between the
initial SOAP sender and the SOAP node which assumes the role of the
ultimate SOAP receiver in the message path, which in our case is the
travel reservation service. Therefore, the Body
and its contents
are implicitly targeted and are expected to be understood by the ultimate
target. The means by which a SOAP node assumes such a role is not defined by
the SOAP specification, and is determined as a part of the overall
application semantics and associated message flow.
Note that a SOAP intermediary may decide to play the role of the ultimate
SOAP receiver for a given message transfer, and thus process the
Body
. However, whilst this sort of a behaviour cannot be
prevented, it is not something that should be done lightly as it may pervert
the intentions of the message's sender, and have undesirable side effects
(such as not processing header blocks that might be targeted at
intermediaries further along the message path).
A SOAP message such as that in Example 1 may be transferred by different underlying protocols and used in a variety of message exchange patterns. For example, with a Web-based access to a travel service, it could be placed in the body of a HTTP POST request. In another protocol binding, it might be sent in an email message (see section 3.2). Section 3 will describe how SOAP messages may be conveyed by a variety of transports. For the time being, we will assume that a mechanism exists for message transfer and concentrate on the details of the messages and their processing.
SOAP version 1.2 is a simple messaging framework for transferring information in the form of XML infosets between a SOAP sender and receiver. The more interesting scenarios typically involve multiple message exchanges. The simplest such exchange is a request-response pattern. Not all request-response exchanges can or need to be modelled as remote procedure calls (RPC). The latter is used when there is a need to model a certain programmatic behavior, with the exchanged messages conforming to a well-defined signature for the remote call and its return. A much larger set of request-response exchanges can be modeled simply as XML-based documents exchanged, where the semantics are at the level of the sending and receiving applications. Section 2.2.1 covers the document exchange case, while section 2.2.2 provides an example of an exchange modeled as a RPC.
Continuing with the travel request application scenario, Example 2 shows a SOAP message returned from the travel service in response to the reservation request message in Example 1. This response seeks to refine some information in the request, namely the choice of airports in the departing city.
<?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"> <env:Header> <m:reservation xmlns:m="http://travelcompany.example.org/reservation" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference> <m:dateAndTime>2001-11-29T13:35:00.000-05:00</m:dateAndTime> </m:reservation> <n:passenger xmlns:n="http://mycompany.example.com/employees" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <n:name>John Q. Public</n:name> </n:passenger> </env:Header> <env:Body> <p:itinerary xmlns:p="http://travelcompany.example.org/reservation/travel"> <p:airportChoices> JFK LGA EWR </p:airportChoices> </p:itinerary> </env:Body> </env:Envelope>
As described earlier, the Body
contains the primary content
of the message, which in this example includes a list of the various
alternatives for the airport, conforming to a schema definition in the
namespace http://travelcompany.example.org/reservation/travel. In this
example, the header blocks from Example 1 are returned
(with some sub-element values altered) in the response. This could allow
message correlation at the SOAP level, but such headers are very likely to
also have other application-specific uses.
The message exchange in Examples 1 and 2 are cases where XML documents conforming to some application-defined schema are exchanged via SOAP messages. Once again, we defer discussion of the means by which such messages are transferred.
It is easy enough to see how such exchanges can build up to a
"conversational" message exchange pattern. Example 3 shows a SOAP message
sent by the traveller in response to that in Example
2 choosing one from the list of airports available. The header block
reference
with the same value of some of the sub-elements
accompanies each message in this conversation, thereby allowing a correlation
between them at the application level.
<?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"> <env:Header> <m:reservation xmlns:m="http://travelcompany.example.org/reservation" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference> <m:dateAndTime>2001-11-29T13:36:50.000-05:00</m:dateAndTime> </m:reservation> <n:passenger xmlns:n="http://mycompany.example.com/employees" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <n:name>John Q.Public</n:name> </n:passenger> </env:Header> <env:Body> <p:itinerary xmlns:p="http://travelcompany.example.org/reservation/travel"> <p:departure> <p:departing>LGA</p:departing> </p:departure> <p:return> <p:arriving>EWR</p:arriving> </p:return> </p:itinerary> </env:Body> </env:Envelope>
One of the design goals of SOAP is to encapsulate remote procedure call functionality using the extensibility and flexibility of XML. Part 2 section 4 of the SOAP specification has defined a uniform representation for RPC invocations and responses. In this section, we continue with our travel reservation service example to illustrate the use of SOAP messages to convey remote procedure calls and their return.
The scenario we have in mind is the payment for the trip using a credit card. We assume that this happens in the context of an overall transaction where the credit card is charged only when the travel and the lodging (not shown here, but presumably reserved in a similar manner) are both confirmed. The passenger provides credit card information and the successful completion of the different activities results in the card being charged and a reservation code returned. This reserve-and-charge interaction between the passenger and the travel service is modeled as a SOAP RPC.
To invoke a SOAP RPC, the following information is needed. Such information may be expressed by a variety of means, including formal Interface Definition Languages:
Note that SOAP does not provide any interface definition language, formal or informal. Note also that the above information differs in subtle ways from information generally needed to invoke other, non-SOAP RPCs.
Items 4 and 5 above are required to ensure that RPC applications that employ SOAP can do so in a manner which is compatible with the architectural principles of the World Wide Web. Very briefly, the simplicity and scalability of the Web is largely due to the fact that there are a few "generic" methods (GET, POST, PUT, DELETE) which can be used to interact with any resource made available on the Web via a URI.
The central role of the URI as the only means to
identify all accessible resources on the Web is the source of the requirement
to provide the information in item 4 above. Part 2 Section 4.1.1provides guidelines on how to identify RPC resources
in a manner that is compatible with this central principle. It does so by
distinguishing aspects of the method and specific parameters in a RPC
definition that serve to identify resources from those that serve other
purposes. In Example 4
below showing an RPC carried in a SOAP message,
the resource to be retrieved is identified by two things: the first is that
it is a reservation (part of the method name), and the second is the specific
instance of a reservation (which is the value of the parameter reference
to the
method). The remainder of the parameters in the RPC are not
resource-identifying, but rather data that is necessary for manipulation of
the resource. It is the recommendation of Part 2 that resources that may be
accessed by SOAP-based RPCs should, where practical, place any such
resource-identifying information as a part of the URI identifying the target
of the RPC. It should be noted, however, that Part 2 does not offer any
algorithm to do so. Such algorithms may
be developed in future.
From a SOAP perspective, there is a SOAP node which "contains" or "supports" the target of the RPC. It is the SOAP node which (appropriately) adopts the role of the ultimate SOAP receiver. The ultimate recipient can identify the "resource" that supports the named procedure or method by looking for its URI. One possibility is that the URI identifying the target is carried in a SOAP header block. Some protocol bindings, such as the HTTP binding, offer a mechanism for carrying the URI outside the SOAP message. In general, one of the properties of a protocol binding specification must be a description of how the target URI is carried as a part of the binding.
A second part of defining SOAP-conveyed RPCs in a Web architecture friendly manner is distinguishing RPCs which are purely for the purpose of resource retrieval from those that perform resource manipulation. A very important - indeed predominant - use of the World Wide Web is pure information retrieval, where the representation of an available resource, identified by an URI, is fetched using a HTTP GET request without affecting the resource in any way. (This is called a safe and idempotent method in HTTP terminology.) The key point is that the publisher of a resource makes available its URI, which consumers may "GET".There are many instances when RPCs are designed for uses which are purely for information retrieval, such as when the state of some resource (or object, in programming terms) is requested. In such instances, the use of a SOAP body to carry the request for the state, with a parameter of the RPC representing the object in question, is seen as counter to the spirit of the Web because the resource is not identified directly via its URI. (In the typical SOAP/RPC usage with HTTP, the HTTP request URI is often not the resource itself but some intermediate entity which has to evaluate the SOAP message to fully identify the resource.)
Item 5 above describes the information that an application designer for a RPC that represent pure retrieval functions needs to make available to the underlying message transfer mechanism to ensure that such RPCs can be represented in a Web-friendly manner. To this end, SOAP 1.2 defines two abstract properties that 1) identify that the invoked "Web method" should be GET, and 2) that the message exchange pattern should be a SOAP Response message exchange pattern, which is one where a non-SOAP request generates a SOAP response. The first property is a specific value for a general feature called the Web Methods Specification feature that allow the identification of the so-called Web method - one of GET, POST, PUT, DELETE whose semantics are as defined in the HTTP specifications - that may be used over the binding. The second is one of two message exchange patterns that have been specified in SOAP 1.2. Section 3 offers more details on message exchange patterns.
Therefore, when a RPC definition is such that all the parts of its method signature can be described as resource-identifying and hence entirely representable by a URI, and the invocation of the operation is considered safe and idempotent, the choice of the Web-method property of GET and the use of a SOAP Response message exchange pattern will ensure that the SOAP RPC is performed in a Web architecture compatible way.
We defer until section 3 the discussion and some concrete examples of how the URI is carried in HTTP, as well as draw the reader's attention to section 3.1.3 which provides detailed examples on how to carry RPCs in the HTTP binding where the purpose appear to be safe and idempotent information retrieval.
For the remainder of this section, we assume that the RPC conveyed in a SOAP message as shown in Example 4 is appropriately targeted and dispatched. Our purpose hereafter is to highlight aspects related to the serialization of RPC requests and returns within the SOAP message.
<?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope" > <env:Header> <t:transaction xmlns:t="http://thirdparty.example.org/transaction" env:encodingStyle="http://example.com/encoding" env:mustUnderstand="true" > 5 </t:transaction> </env:Header> <env:Body> <m:chargeReservation env:encodingStyle="http://www.w3.org/2002/06/soap-encoding" xmlns:m="http://travelcompany.example.org/"> <m:reservation xmlns:m="http://travelcompany.example.org/reservation" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference> </m:reservation> <o:creditCard xmlns:o="http://mycompany.example.com/financial"> <n:name xmlns:n="http://mycompany.example.com/employees"> John Q. Public </n:name> <o:number>123456789099999</o:number> <o:expiration>2005-02</o:expiration> </o:creditCard> </m:chargeReservation> </env:Body> </env:Envelope>
The RPC itself is carried as a child of the Body
element, and
is modelled as a struct
which takes the name of the procedure or
method, in this case chargeReservation
. (A struct
is a
concept from the SOAP Data Model that models a structure or record type
that occurs in some common programming languages. Another alternative offered
by the SOAP Data Model, and which may be used to model the carriage of a RPC
request and response via SOAP is an array
, where parameters are
accessed by their position.) The signature for the RPC in our example has
been designed to take two input (or "in") parameters, the
reservation
of the traveller and the creditCard
information. The latter is also a struct
, which takes three
elements, the card holder's name, the card number
and an
expiration
date.
In this example, the encodingStyle
attribute with a value in
the SOAP encoding
namespace shows that the contents of the chargeReservation
structure have been serialized according to the SOAP encoding rules, i.e.,
the particular rules defined in
Part 2 section 3 of the SOAP specifications. Whilst SOAP specifies this particular encoding scheme,
the specification makes clear that other encoding schemes may be used for
application-specific data within a SOAP message. It is for this purpose that
it provides the encodingStyle
attribute to qualify header blocks
and body sub-elements. The choice of the value for this attribute is an
application-specific decision and the ability of a caller and callee to
interoperate is assumed to have been settled "out-of-band". Section 4.2 shows examples of using other encoding
schemes.
RPCs may also require additional information to be carried, which can be
important for the processing of the call in a distributed environment, but
which are not a part of the formal procedure or method signature. In our
example, the RPC is carried out in the context of an overall transaction
which involves several activities which must all complete successfully before
the RPC returns successfully. Example 4 shows how a
header block transaction
directed at the ultimate recipient
(implied by the absence of the role
attribute) can be used to
carry such information.
Let us assume that the procedure in our charging example has been designed
to have a RPC signature which indicates that there are two output (or "out")
parameters, one providing a reference
number for the reservation
and the other an URL where the details of the reservation may be viewed. The
RPC response is returned in the Body
element of a SOAP message,
with is modelled as a struct
taking the procedure name
chargeReservation
and, as a convention, the word "Response"
appended. This is shown in Example 5a, where the header again identifies the
transaction within which this RPC was performed.
<?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope" > <env:Header> <t:transaction xmlns:t="http://thirdparty.example.org/transaction" env:encodingStyle="http://example.com/encoding" env:mustUnderstand="true" > 5 </t:transaction> </env:Header> <env:Body> <m:chargeReservationResponse env:encodingStyle="http://www.w3.org/2002/06/soap-encoding" xmlns:m="http://travelcompany.example.org/"> <m:reference>FT35ZBQ</m:reference> <m:viewAt> http://travelcompany.example.org/reservations?code=FT35ZBQ </m:viewAt> </m:chargeReservationResponse> </env:Body> </env:Envelope>
RPCs often have signatures where a particular output parameter is distinguished, the so-called "return" value. The SOAP RPC convention offers a way to distinguish this "return" value from the other output parameters in the signature. To show this, let us amend our charging example to have a RPC signature that is almost the same as that for Example 5a, i.e, with the same two "out" parameters, but in addition it also has a "return" value, which is an enumeration with potential values of "confirmed", and "pending". The RPC response with this signature is shown in Example 5b, where the header, as before, identifies the transaction within which this RPC was performed.
<?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope" > <env:Header> <t:transaction xmlns:t="http://thirdparty.example.org/transaction" env:encodingStyle="http://example.com/encoding" env:mustUnderstand="true" > 5 </t:transaction> </env:Header> <env:Body> <m:chargeReservationResponse env:encodingStyle="http://www.w3.org/2002/06/soap-encoding" xmlns:rpc="http://www.w3.org/2002/06/soap-rpc" xmlns:m="http://travelcompany.example.org/"> <rpc:result>m:status</rpc:result> <m:status>confirmed</m:status> <m:reference>FT35ZBQ</m:reference> <m:viewAt> http://travelcompany.example.org/reservations?code=FT35ZBQ </m:viewAt> </m:chargeReservationResponse> </env:Body> </env:Envelope>
The return value is identified by the element result
in the
"rpc" namespace, and
contains the XML Qualified Name (QName) of another element within the
struct
which, in Example 5b, is
m:status
which in turn contains the actual return value,
"confirmed". This technique allows the actual return value to be strongly
typed according to some schema. If the rpc:result
element is
absent, as was the case in Example 5a, the return
value is not present or is of the type void
.
While, in principle, using SOAP for RPC is independent of the decision to use a particular means for transferring the RPC call and its return, certain protocol bindings that support the SOAP request-response message exchange pattern may be more naturally suited for such purposes. A protocol binding supporting this message exchange pattern can provide the correlation between a request and a response. Of course, the designer of a RPC-based application could choose to put a correlation ID relating a call and its return in a SOAP header, thereby making the RPC inependent of any underlying transfer mechanism. In any case, application designers have to be aware of all the characteristics of the particular protocols chosen for transferring SOAP RPCs, such as latency, synchrony, etc.
In the commonly used case, standardized in Part 2 section 7, of using HTTP as the underlying transfer protocol, an RPC invocation maps naturally to the HTTP request and an RPC response maps to the HTTP response. Section 3.1 provides examples of carrying RPCs using the HTTP binding.
However, it is worth keeping in mind that while most examples of SOAP for RPC use the HTTP protocol binding, it is not limited to that means alone.
SOAP provides a model for handling situations when faults arise in the processing of a message. SOAP distinguishes between the conditions that result in a fault, and the ability to signal that fault to the originator of the faulty message or another node. The ability to signal the fault depends on the message transfer mechanism used, and one aspect of the binding specification of SOAP onto an underlying protocol is to specify how faults are signalled, if at all. The remainder of this section assumes that a transfer mechanism is available for signalling faults generated whilst processing received messages, and concentrates on the structure of the SOAP fault message.
The SOAP Body
element has another distinguished role in that
it is the place where such fault information is placed. The SOAP fault model
(see
Part 1, section 5.4) requires that all SOAP-specific and
application-specific faults be reported using a single distinguished
element,
Fault
, carried within the Body
element. The
Fault
element contains two mandatory sub-elements,
Code
and
Reason
, and (optionally) application-specific information in the
Detail
sub-element within the Fault. Another optional sub-element,
Node
, identifies via a URI the SOAP node which generated the
fault, its absence implying that it was the ultimate recipient of the message
which did so. There is another optional sub-element,
Role
, which identifies the role that the node which generated the
fault was playing.
Example 6 shows a SOAP message returned in response to the RPC request in Example 4 indicating a failure to process the RPC carried in the SOAP message.
<?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope" xmlns:rpc='http://www.w3.org/2002/06/soap-rpc'> <env:Body> <env:Fault> <env:Code> <env:Value>env:Sender</env:Value> <env:Subcode> <env:Value>rpc:BadArguments</env:Value> </env:Subcode> </env:Code> <env:Reason xml:lang="en-US">Processing Error</env:Reason> <env:Detail> <e:myfaultdetails xmlns:e="http://travelcompany.example.org/faults" > <message>Name does not match card number</message> <errorcode>999</errorcode> </e:myfaultdetails> </env:Detail> </env:Fault> </env:Body> </env:Envelope>
The Code
sub-element is made up of a mandatory
Value
element, whose content is specified in the SOAP
specification (see
Part 1 section 5.4.6). In Example 6, the
value
uses a standardized Qualified Name (QName
) to
indicate that it is a Sender
fault defined in the SOAP
env
namespace, and therefore related to some syntactical error
or inappropriate information in the message. (When a Sender
fault is received by the sender, it is expected that some corrective action
is taken before a similar message is sent again.) The Subcode
element is optional, and, if present, as it is in this example, qualifies the
parent value further. The structure of the Subcode
element has
been chosen to be hierarchical - each child Subcode
element has
a mandatory
Value
and an optional Subcode
sub-element - to allow
application-specific codes to be carried. In Example
6, the Subcode
denotes that a RPC specific fault, defined in
Part 2 section 4.3, is the cause of the failure to process the
request.
The hierarchical structure of the Code
element allows for an
uniform mechanism for conveying multiple level of fault codes. The first
Value
is a base fault that is specified in the SOAP 1.2
specifications (see
Part 1 section 5.4.6) and must be understood by all SOAP nodes. Nested
values are application-specific, and represent further elaboration or
refinement of the base fault from an application perspective. Some of these
values may well be standardized, such as the RPC codes standardized in SOAP
1.2 (see
Part 2 section 4.3), or some other standards that use SOAP as an
encapsulation protocol. The only requirement for such defining
application-specific subcode values is that they be namespace qualified using
any namespace other than the SOAP env
namespace which
"contain" the "primary" SOAP faults. There is no requirement from a SOAP
perspective that applications need to understand, or even look at all levels
of the subcode values.
The Reason
sub-element is not meant for algorithmic
processing, but rather for human understanding; so, even though this is a
mandatory item, the chosen value need not be standardized. Therefore all that
is required is that it reasonably accurately describe the fault situation.
The absence of a Node
element in Example
6 implies that it is generated by the ultimate receiver of the call. The
Detail
entries are application-specific.
During the processing of a SOAP message, a fault may also be generated if
a mandatory header element is not understood or the information contained in
it cannot be processed. Errors in processing a Header
element is
also signalled using a Fault
element within the
Body
, but the Detail
sub-element is not used, and a
particular distinguished header element, Misunderstood
, in the
SOAP env namespace,
identifies the offending header.
Example 7 shows an example of a response to the RPC in Example 4 indicating a failure to process the
transaction
header block. Note the presence of the
MustUnderstand
fault code in the Body
, and the
identification of the header not understood via a qname
attribute in the special (empty) header block Misunderstood
.
<?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope" xmlns:f='http://www.w3.org/2002/06/soap-faults'> <env:Header> <f:Misunderstood qname='t:transaction' xmlns:t="http://thirdparty.example.org/transaction"/> </env:Header> <env:Body> <env:Fault> <env:Code> <env:Value>env:MustUnderstand</env:Value> </env:Code> <env:Reason xml:lang="en-US">Header not understood</env:Reason> </env:Fault> </env:Body> </env:Envelope>
If there were several mandatory header blocks that were not understood,
then each would be identified by its qname
attribute in a series
of such Misunderstood
sub-elements.
Having established the various syntactical aspects of a SOAP message as well as some basic message exchange patterns, we now provide a general overview of the SOAP processing model (specified in Part 1, Section 2). The SOAP processing model describes the actions taken by a SOAP processor at a node on receiving a SOAP message.
Example 7a shows a SOAP message with several header blocks (with their contents elided for brevity). This will be used in the remainder of this section to illustrate various aspects of the processing model.
<?xml version="1.0" ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"> <env:Header> <p:oneBlock xmlns:p="http://example.com" env:role="http://example.com/Log"> :::: </p:oneBlock> <q:anotherBlock xmlns:q="http://example.com" env:role="http://www.w3.org/2002/06/soap-envelope/role/next"> :::: </q:anotherBlock> <r:aThirdBlock xmlns:r="http://example.com"> :::: </r:aThirdBlock> </env:Header> <env:Body > :::: </env:Body> </env:Envelope>
The SOAP processing model describes the actions taken by a SOAP processor at a node on receiving a SOAP message. There is a requirement for the processor to analyse those parts of a message that are SOAP-specific, namely those elements in the SOAP "env" namespace. Such elements are the envelope itself, the header element and the body element. A first step is, of course, the overall check that the SOAP message is syntactically correct. That is, it conforms to the SOAP XML infoset subject to the restrictions on the use of certain XML constructs - Processing Instructions and Document Type Definitions - as defined in Part 1, section 5.
Further processing of header blocks and the body depend on the
role(s) assumed by the SOAP node for the processing of a given message.
SOAP defines the (optional) role
attribute - syntactically,
anyURI
- that may be present in a header element, which
identifies the role played by the intended target of that header. A SOAP
processor is required to process a header block if it assumes the role
identified by the value of the URI. Three standardized roles have been
defined (see
Part 1, section 2.2), which are
In Example 7a, the header block
oneBlock
is targeted at any SOAP node that plays the role
defined by the URI http://example.com/Log. For purposes of illustration, we
assume that the specification for such a header block requires that any SOAP
processor adopting this role log the entire message.
Every SOAP node receiving a message with a header block that has a
role
attribute of "next" must be capable of processing the
contents of the element, as this is a standardized role that every SOAP node
must be willing to assume. Header elements thus attributed are those which
are expected to be examined and (possibly) processed by the next SOAP node
along the path of a message, assuming that such a header has not been removed
as a result of processing at some node earlier in the message path. In the
above example, the header block anotherBlock
is targeted at the
next node in the message path. In Example 7a, the
SOAP message received by the node playing the role of the
"http://example.com/Log", must also be willing to play the role of "next".
This is also true for the node which is the ultimate recipient of the
message, as it obviously (and implicitly) also plays the "next" role by
virtue of being next in the message path.
The third header block, aThirdBlock
, in Example 7a does not have the role
attribute. It is targeted at a SOAP node which assumes the "ultimateReceiver"
role. The "ultimateReceiver" role (which can be explicitly declared or is
implicit if the role
attribute is absent in a header block) is
played by a SOAP node that assumes the role of the ultimate recipient of a
particular SOAP message. The absence of an actor attribute in the
aThirdBlock
header block means that this header element is
targeted at the SOAP node that assumes the "ultimateReceiver" role.
Note that the Body
element does not have a role
attribute. The body element is always targeted at the SOAP node that
assumes the "ultimateReceiver" role. In that sense, the body element is just
like a header element targeted at the ultimate receiver, but it has been
distinguished to allow for SOAP nodes (typically SOAP intermediaries) to skip
over it if they assume roles other than that of the ultimate receiver. SOAP
does not prescribe any structure for the Body, except that it requires that
any sub-elements be namespace qualified. Some applications, such as Example 1, may choose to organize the Body in blocks, but
this is not of concern to the SOAP processing model.
The Body element also has another distinguished role. It is the container where information on SOAP-specific faults, i.e., failure to process elements of a SOAP message are placed. SOAP defines a special Body block to convey such fault information. Section 2.3 provides examples of this.
If a header element has the standardized role
attribute with
value "none", it means that no SOAP processor should process the contents,
although a processor may need to examine it if the content is data referenced
by another header element that is targeted at the particular SOAP
processor.
The following table summarizes the applicable standardized roles that may be assumed at various SOAP nodes. ("Yes" and "No" means that the corresponding node does or does not, respectively, play the named role.)
Role | absent | "none" | "next" | "ultimateReceiver" |
Node | ||||
initial sender | not applicable | not applicable | not applicable | not applicable |
intermediary | no | no | yes | no |
ultimate receiver | yes | no | yes | yes |
Example 7b augments the previous example by introducing another attribute
for header blocks, the mustUnderstand
attribute.
<?xml version="1.0" ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"> <env:Header> <p:oneBlock xmlns:p="http://example.com" env:role="http://example.com/Log" env:mustUnderstand="true"> :::: </p:oneBlock> <q:anotherBlock xmlns:q="http://example.com" env:role="http://www.w3.org/2002/06/soap-envelope/role/next"> :::: </q:anotherBlock> <r:aThirdBlock xmlns:r="http://example.com"> :::: </r:aThirdBlock> </env:Header> <env:Body > :::: </env:Body> </env:Envelope>
After a SOAP node has correctly identified the header blocks (and possibly
the body) targeted at itself using the role
attribute, the
additional attribute, mustUnderstand
, in the header elements
determines further processing actions that have to be taken. In order to
ensure that SOAP processors do not ignore header blocks which are important
to the overall purpose of the application, SOAP header blocks also provide
for the additional optional attribute, mustUnderstand
, which, if
"true", means that the targeted SOAP processor must process the block
according to the specification of that block. Such a block is colloquially
referred to as a mandatory header block. In fact, processing of the SOAP
message must not even start until the processor has identified all the
mandatory header blocks targeted at itself, and "understood" them.
Understanding a header means that the processor must be prepared to do
whatever is described in the specification of that block. (Keep in mind that
the specifications of header blocks are not a part of the SOAP
specifications.)
In Example 7b, the header block
oneBlock
is marked with a mustUnderstand
value set
to "true", which means that it is mandatory to process this block if the SOAP
node plays the role identified by "http://example.com/log". The other two
header blocks are not so marked, which means that SOAP processor at which
these blocks are targeted need not process them. (Presumably the
specifications for these blocks allow for this.)
A mustUnderstand
value of "true" means that the SOAP
processor must process the header with the semantics described in that
header's specification, or generate a fault. Processing the header
appropriately may include removing the header from any generated SOAP
message, reinserting the header with the same or altered value, or inserting
a new header. The inability to process a mandatory header requires that all
further processing of the SOAP message cease, and a SOAP fault be generated.
The message is not forwarded any further.
The Body element has no mustUnderstand
attribute but it
must be processed by the ultimate recipient. In Example 7b, the ultimate recipient of the message - the
SOAP processor which plays the "ultimatereceiver" role - must process both
the Body as well as the header block aThirdBlock
. It may process
the header block anotherBlock
, as it is targeted at itself (in
the role of "next") but it is not mandatory to do so if the specifications
for processing the blocks do not demand it. (If the specification for
anotherBlock
demanded that it be processed at the ultimate
recipient, it would have required that it be marked with a
mustUnderstand=
"true".)
The role(s) a SOAP node plays when processing a SOAP message can be
determined by many factors. The role could be knowna priori, set by
some out-of-band means, or a node can inspect all parts of a received message
to determine which roles it will assume before processing the message. An
interesting case arises when a SOAP node, during the course of processing a
message, decides that there are additional roles that it needs to adopt. No
matter when this determination is made, externally it must appear as though
the processing model has been adhered to. That is, it must appear as though
the role had been known from the start of the processing of the message. In
particular, the external appearance must be that the
mustUnderstand
checking of any headers with those additional
roles assumed was performed before any processing began. Also, if a SOAP
processor assumes such additional roles, it must ensure that it is prepared
to do everything that the specifications for those roles require.
The following table summarizes how the processing actions for a header
block are qualified by the mustUnderstand
attribute after a node
that has been appropriate targeted (via its role
attribute).
Node | intermediary | ultimate receiver |
mustUnderstand | ||
"true" | must process | must process |
"false" | may process | may process |
absent | may process | may process |
As a result of processing a SOAP message, a SOAP processor may generate a
single SOAP fault if it fails to process a message, or, depending on the
application, generate additional SOAP messages for consumption at other SOAP
nodes. A SOAP fault is a SOAP message with a standardized Body
sub-element identifying itself as such. SOAP makes a distinction between
generating a fault and ensuring that the fault is returned to the originator
of the message or to another appropriate node which can benefit from this
information.
Part 1 section 5.4 of the SOAP specifications describes the structure of the fault message while the SOAP processing model defines the conditions under which it is generated. However, whether a generated fault can be propagated appropriately depends on the protocol binding chosen for message exchange. The specification does not define what happens if faults are generated during the propagation of one-way messages. The other normative binding, which is the HTTP binding, offers the HTTP response as a means for reporting a fault in the request.
Examples of fault handling were provided in section 2.3.
SOAP messages may be exchanged using a variety of "underlying" protocols,
including other application layer protocols. The specification of how SOAP
messages may be passed from one SOAP processor to another using an underlying
protocol is called a protocol binding. Part 1 of the SOAP specifications
defines a SOAP message in the form of an XML Information Set [12], i.e., in terms of element and attribute information
items of an abstract "document" called the Envelope
(see
Part 1, section 5.1). Any SOAP Envelope
infoset
representation will be made concrete through a protocol binding, whose job,
among other things, it is to provide a serialized representation of the
infoset that can be conveyed to the next SOAP node in the message path in a
manner such that the infoset can be reconstructed without loss of
information. In typical examples of SOAP messages, and certainly in all the
examples in this Primer, the serialization shown is that of a well-formed XML
1.0 document. However, there may be protocol bindings - for example a
protocol binding between two SOAP nodes over a limited bandwidth interface -
where an alternative, compressed serialization of the same infoset may be
chosen. Another serialization, chosen for a different purpose, might be an
encrypted form.
In addition to providing a concrete realization of a SOAP infoset between adjacent SOAP nodes along a SOAP message path, a protocol binding may provide native mechanisms that support features that may be needed by a SOAP application. For example, a typical usage scenario might require many concurrent request-response exchanges between adjacent SOAP nodes, in which case the feature that is required is the ability to correlate a request with a response. If SOAP message exchanges were being transported over a datagram protocol like UDP, obviously such message correlation would have to be provided elsewhere, perhaps directly by the application or more likely as a part of the SOAP infosets being exchanged. In the latter case, the message correlation feature has a binding-specific expression within the SOAP envelope, i.e., as a SOAP header block. However, if the SOAP infosets were being exchanged using an underlying protocol that was itself request/response, the application can implicitly "inherit" this feature provided by the binding and no further support need be provided at the application or the SOAP level. (In fact, the HTTP binding for SOAP takes advantage of just this feature of HTTP.)
However, a SOAP message may travel over several hops between a sender and the ultimate receiver, where each hop may be a different protocol binding. In other words, a feature (e.g., message correlation, reliability) that is supported by the protocol binding in one hop may not be supported by another in the message path. SOAP itself does not provide any mechanism for hiding the differences in features provided by different underlying protocols. However, any feature that is required by a particular application, but which may not be available in the anticipated underlying infrastructure along the message path, can be compensated for by being carried as a part of the SOAP message infoset. That is achieved using the SOAP extension mechanism, i.e., as a SOAP header block.
Thus it is apparent that there are a number of issues that have to be tackled by an application designer to accomplish a particular application semantics, including how to take advantage of the native features of underlying protocols that are available for use in the chosen environment. Part 1 Section 4.2 provides a general framework for describing how SOAP-based applications may choose to use the features provided by an underlying protocol binding to accomplish a particular application semantics. It is intended to provide guidelines for writing interoperable protocol binding specifications for SOAP.
Among other things, a binding specification must define one particular feature, namely the message exchange pattern(s) that it supports. Part 2 defines two such message exchange patterns, namely a Request-Response message exchange pattern where one SOAP message is exchanged in each direction between two adjacent SOAP nodes, and a SOAP Response message exchange pattern which consists of a non-SOAP message acting as a response followed by a SOAP message included as a part of the response.
Part 2 also offers the application designer a general feature called the Web Methods Specification feature that allow the identification of the so-called Web method - one of GET, POST, PUT, DELETE whose semantics are as defined in the HTTP specifications - that may be used over the binding. This feature is supported by the SOAP HTTP binding, although, in principle, it is available to all bindings.
Part 2 section 7specifies one standardized protocol binding using the binding framework of Part 1, namely how SOAP is used in conjunction with HTTP as the underlying protocol. SOAP 1.2 restricts itself to the definition of a HTTP binding allowing only the use of the POST method in conjunction with the Request-Response message exchange pattern and the GET method with the SOAP Response message exchange pattern. Other specifications in future could define SOAP bindings to HTTP or other transports that make use of the other Web methods (i.e., PUT, DELETE).
The next sections show examples of two underlying bindings for SOAP, namely those to HTTP and email. It should be emphasized again that the only normative binding for SOAP 1.2 messages is to HTTP. The example in section 3.2 showing email as a transport mechanism for SOAP is simply meant to suggest that other choices for the transfer of SOAP messages are possible, although not standardized at this time. A W3C Note [14] offers an application of the SOAP protocol binding framework of Part 1 by describing an experimental binding of SOAP to email transport, specifically RFC 2822-based message transport.
HTTP has a well-known connection model and a message exchange pattern. The client identifies the server via a URI, connects to it via the underlying TCP/IP network, issues a HTTP request message and receives a HTTP response message over the same TCP connection. HTTP implicitly correlates its request message with its response message; therefore, an application using this binding can chose to infer a correlation between a SOAP message sent in the body of a HTTP request message and a SOAP message returned in the HTTP response. Similarly, HTTP identifies the server endpoint via a URI, which can also serve as the identification of a SOAP processor at the node.
HTTP allows for multiple intermediaries between the initial client and the server identified by the request URI, in which case the request/response model is a series of such pairs. Note, however, that HTTP intermediaries are distinct from SOAP intermediaries.
The HTTP binding in Part 2 makes use of the Web Methods Specification feature to allow applications full control of the so-called Web method - restricting it to one of GET or POST - to use over the HTTP message exchange. In addition, it makes use of two message exchange patterns that offer applications two ways of exchanging SOAP messages via HTTP:1)the use of the HTTP POST method for conveying SOAP messages in the bodies ofHTTP request and response messages, and 2) the use of the HTTP GET method in a HTTP request to return a SOAP message in the body of a HTTP response. The first usage pattern is the HTTP-specific instantiation of a binding feature called the SOAP request-response message exchange pattern, whilst the second uses a feature called the SOAP response message exchange pattern.
The purpose of providing these two types of usages is to accomodate the two interaction paradigms which are well established on the World Wide Web, namely the use of data within the body of a HTTP POST to create or modify the state of a resource identified by the URI to which the HTTP request is destined; and, second, the ability to use a HTTP GET request to obtain a representation of a resource without altering its state in any way. In the first case, the SOAP-specific aspect of concern to us is that the body of the HTTP POST request is a SOAP message which has to be processed (per the SOAP processing model) as a part of the application-specific processing required to conform to the POST semantics. In the second case, the typical usage that is forseen is the case where the representation of the resource that is being requested is returned not as a HTML, or indeed a generic XML document, but as a SOAP message. That is, the HTTP content type header of the response message identifies it as being of media type "application/soap+xml". Presumably, there will be publishers of resources on the Web who determine that such resources are best retrieved and made available in the form of SOAP messages. Note, however, that resources can, in general, be made available in multiple representations, and the desired or preferred representation is indicated by the requesting application using the HTTP Acceptheader.
One further aspect of the SOAP HTTP binding is the question of how an application determines which of these two types of message exchange patterns to use. Part 2 offers guidance on circumstances when applications may use one of the two specified message exchange patterns. (It is guidance - albeit a strong one - as it is phrased in the form of a "SHOULD" in the specifications rather than an absolute requirement identified by the word "MUST".) The SOAP response message exchange pattern with the HTTP GET method is used when an application is assured that the message exchange is for the purposes of information retrieval, where the information resource is "untouched" as a result of the interaction. Such interactions are referred to as safe and idempotent in the HTTP specification. As the HTTP SOAP GET usage does not allow for a SOAP message in the request, applications that need features in the outbound interaction that can only be supported by a binding-specific expression within the SOAP infoset (i.e., as SOAP header blocks) obviously cannot make use of this message exchange pattern. Note that the HTTP POST binding is available for use in all cases.
The following subsections provide examples of the use of these two message exchange patterns defined for the HTTP binding.
Using the HTTP binding with the SOAP Response message exchange pattern is restricted to the HTTP GET method. This means that the response to a HTTP GET request from a requesting SOAP node is a SOAP message in the HTTP response.
Example 8a shows a
HTTP GET directed by the traveller's application (in our continuing travel
reservation scenario) at the URIhttp://travelcompany.example.org/reservations?code=FT35ZBQ
where the traveler's itinerary may be viewed. (How
this URL was made available can be seen in Example 5a.)
GET /travelcompany.example.org/reservations?code=FT35ZBQ HTTP/1.1 Host: travelcompany.example.org Accept: text/html, application/soap+xml
The HTTP Accept header is used to indicate the preferred representation of the resource being requested, which in this example is an "application/soap+xml" media type for consumption by a machine client, rather than the "text/html" media type for rendition by a browser client for consumption by a human.
Example 8b shows the HTTP response to the GET in Example 8a. The body of the HTTP response contains a SOAP message showing the travel details.
HTTP/1.1 200 OK Content-Type: application/soap+xml; charset="utf-8" Content-Length: nnnn <?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"> <env:Header> <m:reservation xmlns:m="http://travelcompany.example.org/reservation" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference> <m:dateAndTime>2001-11-30T16:25:00.000-05:00</m:dateAndTime> </m:reservation> </env:Header> <env:Body> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:x="http://travelcompany.example.org/vocab#"> <x:ReservationRequest rdf:about="http://travelcompany.example.org/reservations?code=FT35ZBQ"> <x:passenger>John Q. Public</x:passenger> <x:outbound> <x:TravelRequest> <x:to>LAX</x:to> <x:from>LGA</x:from> <x:date>12-14-01</x:date> </x:TravelRequest> </x:outbound> <x:return> <x:TravelRequest> <x:to>JFK</x:to> <x:from>LAX</x:from> <x:date>12-20-01</x:date> </x:TravelRequest> </x:return> </x:ReservationRequest> </rdf:RDF> </env:Body> </env:Envelope>
Note that the reservation details could well have been returned as a (X)HTML document, but we wanted to show a case where the reservation application is returning the state of the resource (the reservation) in a data-centric media form (a SOAP message) which can be machine processed, instead of (X)HTML which would be processed by a browser. Indeed, in the most likely anticipated uses of SOAP, the consuming application will not be a browser.
In Example 8b, the
body of the SOAP message contains a description of the itinerary using the
encoding of a graph of resources and their properties using the syntax of the
Resource Description Framework (RDF) [10]. (Very briefly,
as RDF syntax or usage is not the subject of this primer, an RDF graph
describes resources - such as the travel reservation resource available
at http://travelcompany.example.org/reservations?code=FT35ZBQ
- to other
resources (or values) via properties, such as the passenger
,
the outbound
andreturn
dates of
travel.)
Returning a SOAP message in this particular RDF format for the itinerary might have been chosen by the publisher of this resource to allow, for instance, the traveller's application to store it in a RDF-capable calendar application, which could then be queried in complex ways.
Also, as shown in the example, the use of SOAP in the HTTP response body offers the possibility of expressing some application-specific feature through the use of SOAP headers. By using SOAP, the application is provided with a useful and consistent framework and processing model for expressing such features.
Using the HTTP binding with the SOAP Request-Response message exchange pattern is restricted to the HTTP POST method.
Examples 9 and 10 show an example of a HTTP binding using the SOAP request-response message exchange pattern, using the same scenario as that for Example 4 and Example 5a, respectively, namely conveying a RPC and its return in the body of a SOAP message. Here we concentrate on the HTTP headers and their role.
Note that the use of this message exchange pattern in the HTTP binding is available to all applications, whether they are document-centric exchanges or RPC-centric (as in our examples).
When using HTTP, the request URI indicates the resource to which the invocation is "posted". Other than it be a valid URI, SOAP places no restriction on the form of an address (see [3] for more information on URIs).
Example 9 shows a RPC request directed at the reservations application at the travel service available at the URI "http://travelcompany.example.org/Reservations". The SOAP message is sent in the body of a HTTP POST method directed at the above-mentioned URI. When placing SOAP messages in HTTP bodies, the HTTP Content-type header must be chosen as "application/soap+xml".
POST /Reservations HTTP/1.1 Host: travelcompany.example.org Content-Type: application/soap+xml; charset="utf-8" Content-Length: nnnn <?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope" > <env:Header> <t:transaction xmlns:t="http://thirdparty.example.org/transaction" env:encodingStyle="http://example.com/encoding" env:mustUnderstand="true" > 5 </t:transaction> </env:Header> <env:Body> <m:chargeReservation env:encodingStyle="http://www.w3.org/2002/06/soap-encoding" xmlns:m="http://travelcompany.example.org/"> <m:reservation xmlns:m="http://travelcompany.example.org/reservation" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference> </m:reservation> <o:creditCard xmlns:o="http://mycompany.example.com/financial"> <n:name xmlns:n="http://mycompany.example.com/employees"> John Q. Public </n:name> <o:number>123456789099999</o:number> <o:expiration>2005-02</o:expiration> </o:creditCard> </m:chargeReservation> </env:Body> </env:Envelope>
Example 10 shows the RPC return (with details elided) sent by the travel service in the corresponding HTTP response to the request from Example 5a. SOAP using HTTP transport follows the semantics of the HTTP status codes for communicating status information in HTTP. For example, the 2xx series of HTTP status codes indicate that the client's request (including the SOAP component) was successfully received, understood, and accepted etc.
HTTP/1.1 200 OK Content-Type: application/soap+xml; charset="utf-8" Content-Length: nnnn <?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope" > <env:Header> :::: </env:Header> <env:Body> :::: </env:Body> </env:Envelope>
If an error occurs while processing the request, the HTTP binding specification requires that a HTTP 500 "Internal Server Error" be used with an embedded SOAP message containing a SOAP fault indicating the server-side processing error.
Example 11 is the same scenario as Example 6, but with the HTTP headers added.
HTTP/1.1 500 Internal Server Error Content-Type: application/soap+xml; charset="utf-8" Content-Length: nnnn <?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"> <env:Body> <env:Fault> <env:Code> <env:Value>env:Receiver</env:Value> </env:Code> <env:Reason xml:lang="en-US">Processing Error</env:Reason> <env:Detail> <e:myfaultdetails xmlns:e="http://travelcompany.example.org/faults" > <message>Name does not match card number</message> <errorcode>999</errorcode> </e:myfaultdetails> </env:Detail> </env:Fault> </env:Body> </env:Envelope>
Part 2 Section 7.4.1.2 provides detailed behaviour for handling the various possible HTTP response codes, i.e., the 2xx (successful), 3xx (redirection), 4xx (client error) and 5xx (server error).
A very important - indeed predominant - use of the World Wide Web is pure information retrieval, where the representation of an available resource, identified by an URI, is fetched using a HTTP GET request without affecting the resource in any way. (This is called a safe and idempotent method in HTTP terminology.) The key point is that the publisher of a resource makes available its URI, which consumers may "GET".
There are many instances when RPCs are designed for uses which are purely for information retrieval, such as when the state of some resource (or object, in programming terms) is requested. In such instances, the use of a SOAP body to carry the request for the state, with a parameter of the RPC representing the object in question, is seen as counter to the spirit of the Web because the resource is not identified by the request URI of the HTTP GET. (In the typical SOAP/RPC usage scenario, the HTTP request URI is often not the resource itself but some intermediate entity which has to evaluate the SOAP message to identify the resource.)
To highlight the changes needed, Example 12a shows
the way that is NOT recommended for doing safe information retrieval on the
Web. This is an example of a RPC carried in a SOAP message, again using our
travel reservation theme, where the request is to retrieve the itinerary for
a particular reservation identified by one of the parameters,
reference
, of the RPC. (For purposes of this discussion, we
assume that the application using this RPC request does not need features
which require the use of SOAP headers.)
POST /Reservations HTTP/1.1 Host: travelcompany.example.org Content-Type: application/soap+xml; charset="utf-8" Content-Length: nnnn <?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope" > <env:Body> <m:retrieveItinerary env:encodingStyle="http://www.w3.org/2002/06/soap-encoding" xmlns:m="http://travelcompany.example.org/"> <m:reference> FT35ZBQ </m:reference> </m:retrieveItinerary> </env:Body> </env:Envelope>
Note that the resource to be retrieved is not identified by the target URI in the HTTP request but has to be obtained by looking within the SOAP envelope. Thus, it is not possible, as would be the case with other "gettable" URIs on the Web, to make this available via HTTP alone to consumers on the World Wide Web.
Part
2 section 4.1 offers recommendations on how RPCs that constitute safe and
idempotent information retrievals may be defined in a Web-friendly manner. It
does so by distinguishing aspects of the method and specific parameters in a
RPC definition that serve to identify resources from those that serve other
purposes. In Example 12a, the resource to be retrieved is identified by two
things: the first is that it is an itinerary (part of the method name), and
the second is the reference to a specific instance (a parameter to the
method.) In such a case, the recommendation is that these
resource-identifying parts be made available in the HTTP request URI
identifying the resource, as for example, as follows:
http://travelcompany.example.org/reservations/itinerary?record=FT35ZBQ
.
Furthermore, in the case that the entire resource may be identified by a URI, and the supplier of the resource can be reassured that a retrieval request is safe, SOAP 1.2 recommends that the SOAP Response message exchange pattern be used as described in section 3.1.2. Example 12b shows the preferred way for a SOAP node to request the safe retrieval of a resource.
GET /Reservations/itinerary?record=FT35ZBQ HTTP/1.1 Host: travelcompany.example.org Accept: application/soap+xml
It should be noted that SOAP 1.2 does not specify any algorithm on how to compute a URI from the definition of a RPC which has been determined to represent pure information retrieval.
Note, however, that if the application requires the use of features that can only have a binding-specific expression within the SOAP infoset, i.e., using SOAP header blocks, then the application must choose HTTP POST method with a SOAP message in the request body.
It would also require the use of the SOAP request-response message exchange pattern implemented via a HTTP POST if the RPC signature
included data (parameters) which were not resource-identifying. Even in this
case, the HTTP POST with a SOAP message conveying the RPC can be represented
in a Web-friendly manner. As with the use of the GET, Part 2 recommends that
any part of the RPC signature that serves to identify the resource to which
the request is POSTed be identified in the HTTP request URI. The same
parameters may, of course, be retained in the encoded RPC in the SOAP
Body
element.
Example 13 is the same
as that in Example 9, except that the request
URI has been modified to include thename
of the
traveller, which serves to identify the resource (the reservation in
question, which is being confirmed and paid for), whilst the other parameters
in the RPC, such as the creditCard
number are ancilliary data to
be processed by the resource. Note, however, that the all the parameters in
the RPC signature have been retained as in Example 9 in their encoded form in
the SOAP Body
element.
POST /Reservations?name=John%20Q.%20Public HTTP/1.1 Host: travelcompany.example.org Content-Type: application/soap+xml; charset="utf-8" Content-Length: nnnn <?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope" > <env:Header> <m:reservation xmlns:m="http://travelcompany.example.org/reservation" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference> <m:dateAndTime>2001-11-29T13:36:50.000-05:00</m:dateAndTime> </m:reservation> <t:transaction xmlns:t="http://thirdparty.example.org/transaction" env:encodingStyle="http://example.com/encoding" env:mustUnderstand="true" > 5 </t:transaction> </env:Header> <env:Body> <m:reserveAndCharge env:encodingStyle="http://www.w3.org/2002/06/soap-encoding" xmlns:m="http://travelcompany.example.org/"> <n:name xmlns:n="http://mycompany.example.com/employees"> John Q. Public </n:name> <o:creditCard xmlns:o="http://mycompany.example.com/financial"> <o:number>123456789099999</o:number> <o:expiration>2005-02</o:expiration> </o:creditCard> </m:reserveAndCharge> </env:Body> </env:Envelope>
In other words, as seen from the above examples, the recommendation in the SOAP specifications is to use URIs in a Web-architecture compatible way - that is, as resource identifiers - whether or not it is GET or POST that is used.
Application developers can use the Internet email infrastructure to move SOAP messages as either email text or attachments. The examples shown below offer one way to carry SOAP messages, and should not be construed as being the standard way of doing so. The SOAP version 1.2 specifications do not specify such a binding.
Example 14 shows the travel reservation request message from Example 1 carried as an email message between a sending and receiving mail user agent. It is implied that the sender and receiver nodes also have SOAP capabilities, to which the body of the email is delivered for processing.
From: john.public@mycompany.example.com To: reservations@travelcompany.example.org Subject: Travel to LA Date: Thu, 29 Nov 2001 13:20:00 EST Message-Id: <EE492E16A090090276D208424960C0C@mycompany.example.com> <?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"> <env:Header> <m:reservation xmlns:m="http://travelcompany.example.org/reservation" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</reference> <m:dateAndTime>2001-11-29T13:20:00.000-05:00</m:dateAndTime> </m:reservation> <n:passenger xmlns:n="http://mycompany.example.com/employees" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <n:name>John Q. Public</n:name> </n:passenger> </env:Header> <env:Body> <p:itinerary xmlns:p="http://travelcompany.example.org/reservation/travel"> <p:departure> <p:departing>New York</p:departing> <p:arriving>Los Angeles</p:arriving> <p:departureDate>2001-12-14</p:departureDate> <p:departureTime>late afternoon</p:departureTime> <p:seatPreference>aisle</p:seatPreference> </p:departure> <p:return> <p:departing>Los Angeles</p:departing> <p:arriving>New York</p:arriving> <p:departureDate>2001-12-20</p:departureDate> <p:departureTime>mid morning</p:departureTime> <p:seatPreference/> </p:return> </p:itinerary> <q:lodging xmlns:q="http://travelcompany.example.org/reservation/hotels"> <q:preference>none</q:preference> </q:lodging> </env:Body> </env:Envelope>
The header in Example 14 is in the standard form [RFC 2822] for email messages.
While an email is a one-way message exchange, and no guarantee of delivery is provided, email infrastructures like the Simple Mail Transport Protocol (SMTP) specification [9] offer a delivery notification mechanism which, in the case of SMTP, are called Delivery Status Notification (DSN) and Message Disposition Notification (MDN). These notifications take the form of email messages sent to the email address specified in the mail header. Applications, as well as email end users, can use these mechanisms to provide the status of an email transmission, but these, if delivered, are notifications at the SMTP level. The application developer must fully understand the capabilities and limitations of these delivery notifications or risk assuming a successful data delivery when none occurred.
SMTP delivery status messages are separate from message processing at the
SOAP layer. Resulting SOAP responses to the contained SOAP data will be
returned through a new email message which may or may not have a link to the
original requesting email at the SMTP level. The use of the RFC 2822
In-reply-to:
header can achieve a correlation at the SMTP level,
but does not necessarily offer a correlation at the SOAP level.
Example 15 is exactly the same scenario as described for Example 2, which shows the SOAP message (body details
elided for brevity) sent from the travel service to the passenger seeking
clarification on some reservation details, except that it is carried as an
email message. In this example, the original email'sMessage-Id
is carried in the additional email header In-reply-to:
, which
correlates email messages at the SMTP level, but cannot provide a
SOAP-specific correlation. In this example, the application relies on the
reservation
header block to correlate SOAP messages. Again, how
such correlation is achieved are functions of how such applications are
designed, and is not within the scope of SOAP.
From: reservations@travelcompany.example.org To: john.public@mycompany.example.com Subject: Which NY airport? Date: Thu, 29 Nov 2001 13:35:11 EST Message-Id: <200109251753.NAA10655@travelcompany.example.org> In-reply-to:<EE492E16A090090276D208424960C0C@mycompany.example.com> <?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"> <env:Header> <m:reservation xmlns:m="http://travelcompany.example.org/reservation" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</reference> <m:dateAndTime>2001-11-29T13:35:00.000-05:00</m:dateAndTime> </m:reservation> <n:passenger xmlns:n="http://mycompany.example.com/employees" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <n:name>John Q. Public</n:name> </n:passenger> </env:Header> <env:Body> <p:itinerary xmlns:p="http://travelcompany.example.org/reservation/travel"> <p:airportChoices> ::::: </p:airportChoices> </p:itinerary> </env:Body> </env:Envelope>
Our application scenario offers us an opportunity to expose some uses of SOAP intermediaries. Recall that the basic exchange was the exchange of a travel reservation request between a passenger and a travel service. SOAP does not specify how such a message path is determined and followed. That is outside the scope of the SOAP specification. It does describe, though, how a SOAP node should behave if it receives a SOAP message for which it may not be the ultimate recipient.
In the following example, we introduce a SOAP node in the request path,
which intercepts the message shown in Example 1. One
example of such a node could be a corporate travel office which logs all
travel requests. Note that the header blocks reservation
and
passenger
in that example are intended for the node(s) that play
the role "next", which means that it is targeted at the next SOAP node in the
message path that receives the message. The header blocks are mandatory (the
mustUnderstand
attribute is set to "true"), which means that the
node must have knowledge (through an external specification of the header
blocks' semantics) of what to do. A logging specification for such header
blocks might simply require that various details of the message be recorded
at every node that receives such a message, and that the message be relayed
along the message path unchanged.
A more complex scenario is one where the SOAP message is amended in some
way. In the following example, we assume that the corporate travel
application attaches a header block to the SOAP message before relaying it
along its message path towards the travel service - the ultimate recipient.
The specification of such a header block might require that the ultimate
recipient (and only the ultimate recipient, as implied by the absence of the
role
attribute) make use of the information conveyed by it when
processing the body of the message.
Example 16 shows an intermediary adding an additional header block,
travelPolicy
, intended for the ultimate recipient which includes
information that qualifies the application-level processing of this travel
request.
<?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"> <env:Header> <m:reservation xmlns:m="http://travelcompany.example.org/reservation" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</reference> <m:dateAndTime>2001-11-29T13:20:00.000-05:00</m:dateAndTime> </m:reservation> <n:passenger xmlns:n="http://mycompany.example.com/employees" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <n:name>John Q. Public</n:name> </n:passenger> <z:travelPolicy xmlns:z="http://mycompany.example.com/policies" env:mustUnderstand="true"> <z:class>economy</z:class> <z:fareBasis>non-refundable<z:fareBasis> <z:exceptions>none</z:exceptions> </z:travelPolicy> </env:Header> <env:Body> <p:itinerary xmlns:p="http://travelcompany.example.org/reservation/travel"> <p:departure> <p:departing>New York</p:departing> <p:arriving>Los Angeles</p:arriving> <p:departureDate>2001-12-14</p:departureDate> <p:departureTime>late afternoon</p:departureTime> <p:seatPreference>aisle</p:seatPreference> </p:departure> <p:return> <p:departing>Los Angeles</p:departing> <p:arriving>New York</p:arriving> <p:departureDate>2001-12-20</p:departureDate> <p:departureTime>mid morning</p:departureTime> <p:seatPreference/> </p:return> </p:itinerary> <q:lodging xmlns:q="http://travelcompany.example.org/reservation/hotels"> <q:preference>none</q:preference> </q:lodging> </env:Body> </env:Envelope>
While SOAP specifies a particular encoding scheme (see
Part 2 section 3), the specification makes clear that other encoding
schemes may be used for application-specific data within a SOAP message. For
this purpose it provides the attribute
encodingStyle
to qualify header blocks and child elements of
the SOAP Body
element. It signals a serialization scheme for the
nested contents or at least until another element is encountered which
indicates another encoding style for its nested contents. The choice of the
value for the encodingStyle
attribute is an application-specific
decision and the ability to interoperate is assumed to have been settled
"out-of-band".
We illustrate the use of an alternative encoding scheme in Example 17. Continuing with our travel reservation theme, this example shows a SOAP message which might be sent to the passenger from the travel service after the reservation is confirmed, showing the travel details. (The same message was used in Example 8b in another context.)
<?xml version='1.0' ?> <env:Envelope xmlns:env="http://www.w3.org/2002/06/soap-envelope"> <env:Header> <m:reservation xmlns:m="http://travelcompany.example.org/reservation" env:role="http://www.w3.org/2002/06/soap-envelope/role/next" env:mustUnderstand="true"> <m:reference>uuid:093a2da1-q345-739r-ba5d-pqff98fe8j7d</m:reference> <m:dateAndTime>2001-11-30T16:25:00.000-05:00</m:dateAndTime> </m:reservation> </env:Header> <env:Body> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:x="http://travelcompany.example.org/vocab#"> <x:ReservationRequest rdf:about="http://travelcompany.example.org/reservations?code=FT35ZBQ"> <x:passenger>John Q. Public</x:passenger> <x:outbound> <x:TravelRequest> <x:to>LAX</x:to> <x:from>LGA</x:from> <x:date>12-14-01</x:date> </x:TravelRequest> </x:outbound> <x:return> <x:TravelRequest> <x:to>JFK</x:to> <x:from>LAX</x:from> <x:date>12-20-01</x:date> </x:TravelRequest> </x:return> </x:ReservationRequest> </rdf:RDF> </env:Body> </env:Envelope>
Body
elementIn Example 17, the body of the SOAP message
contains a description of the itinerary using the encoding of a graph of
resources and their properties using the syntax of the Resource Description
Framework (RDF) [10]. (Very briefly, as RDF syntax or
usage is not the subject of this primer, an RDF graph describes resources -
such as the travel reservation resource available at
http://travelcompany.example.org/reservations?code=FT35ZBQ
- to
other resources (or values) via properties, such as the
passenger
, the outbound
and return
dates of travel. The RDF encoding for the itinerary might have been chosen,
for example, to allow the passenger to store it in a RDF-capable calendar
application, which could then be queried in complex ways.)
SOAP version 1.2 has a number of changes in syntax and provides additional (or clarified) semantics from those described in SOAP 1.1 [11]. The following is a list of features where the two specifications differ. The purpose of this list is to provide the reader with a quick and easily accessible summary of the differences between the two specifications. The following list has been put in categories purely for ease of reference, and in some cases, an item might equally well have been placed in one or another category.
Document structure
Additional or changed syntax
encodingStyle
attribute to
appear on the SOAP Envelope
, whilst SOAP 1.1 allows it to
appear on any element.Misunderstood
header element for
conveying information on a mandatory header block which could not be
processed, as indicated by the presence of a MustUnderstand
fault code. SOAP 1.1 provided the fault code, but no details on its
use.mustUnderstand
attribute in header elements takes the
(logical) value "true" or "false" whilst in SOAP 1.1 they are the literal
value "1" or "0" respectively.DataEncodingUnknown
.actor
with
role
but with essentially the same semantics.Code
and
Reason
, respectively, for what used to be called
faultcode
and faultstring
in SOAP 1.1Code
element, and introduces two new optional subelements,
Node
and Role
.SOAP HTTP binding
SOAPAction
HTTP header
defined in SOAP 1.1 has been removed, and a new HTTP status code 427 has
been sought from IANA for indicating (at the discretion of the HTTP
origin server) that it is required by the server application. The
contents of the former SOAPAction
HTTP header are now
expressed as a value of an "action" attribute of the
"application/soap+xml" media type that is signaled in the HTTP
binding.RPC
rpc:result
element accessor for
RPCs.SOAP encodings
href
attribute in SOAP 1.1 (of type
anyURI
) is called ref
in SOAP 1.2 and is of
type IDREF
.[1] W3C Working Draft "SOAP 1.2 Part 1: Messaging Framework", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen, 2 October 2001 (See http://www.w3.org/TR/soap12-part1.)
[2] W3C Working Draft "SOAP 1.2 Part 2: Adjuncts", Martin Gudgin, Marc Hadley, Jean-Jacques Moreau, Henrik Frystyk Nielsen, 2 October 2001 (See http://www.w3.org/TR/soap12-part2.)
[3] IETF "RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax", T. Berners-Lee, R. Fielding, L. Masinter, August 1998. Available at http://www.ietf.org/rfc/rfc2396.txt.
[4] IETF "RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1", R. Fielding, J. Gettys, J. C. Mogul, H. Frystyk, T. Berners-Lee, January 1997. Available at http://www.ietf.org/rfc/rfc2616.txt.
[5] W3C Recommendation "Extensible Markup Language (XML) 1.0 (Second Edition)", Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 6 October 2000. Available at http://www.w3.org/TR/REC-xml.
[6] W3C Recommendation "Namespaces in XML", Tim Bray, Dave Hollander, Andrew Layman, 14 January 1999. Available at http://www.w3.org/TR/REC-xml-names/.
[7] W3C Recommendation "XML Schema Part 1: Structures", Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2 May 2001. Available at http://www.w3.org/TR/xmlschema-1/
[8] W3C Recommendation "XML Schema Part 2: Datatypes", Paul V. Biron, Ashok Malhotra, 2 May 2001. Available at http://www.w3.org/TR/xmlschema-2/
[9] SMTP is defined in a series of RFCs:
[10] Resource Description Framework (RDF) Model and Syntax Specification, O. Lassila and R. Swick, Editors. World Wide Web Consortium. 22 February 1999. The latest version of RDF model and syntax is available at http://www.w3.org/TR/REC-rdf-syntax.
[11] W3C Note "Simple Object Access Protocol (SOAP) 1.1", Don Box et al, 8 May, 2000 (available at http://www.w3c.org/TR/SOAP/)
[12] W3C Recommendation "XML Information Set", John Cowan, Richard Tobin, 24 October 2001. (See http://www.w3.org/TR/xml-infoset/)
[13] IETF Internet Draft "The 'application/soap+xml' media type", M. Baker, M. Nottingham, "draft-baker-soap-media-reg-01.txt", June 19, 2002 (work in progress). (See http://www.w3.org/2000/xp/Group/2/06/18/draft-baker-soap-media-reg-01.txt)
[14] W3C Note "SOAP Version 1.2 Email Binding", Highland Mary Mountain et al, draft June 13, 2002. (See http://www.w3.org/TR/soap12-email.)
Highland Mary Mountain (Intel) provided the initial material for the section on the SMTP binding. Paul Denning provided material for a usage scenario, which has since been moved to the Usage Scenarios WD. Stuart Williams, Oisin Hurley, Chris Ferris, Lynne Thompson, John Ibbotson, Marc Hadley and Jean-Jacques Moreau provided detailed comments. Jacek Kopecky provided a list of RPC and SOAP encoding changes.
This document is the work of the W3C XML Protocol Working Group.
Members of the Working Group are (at the time of writing, and by alphabetical order): Yasser alSafadi (Philips Research), Vidur Apparao (Netscape), Camilo Arbelaez (WebMethods), Mark Baker (Idokorro Mobile), Carine Bournez (W3C), Michael Champion (Software AG), Paul Cotton (Microsoft Corporation), Glen Daniels (Macromedia), Paul Denning (Mitre), Frank DeRose (Tibco), Colleen Evans (Progress Software), David Fallside (Chair, IBM), Chris Ferris (Sun Microsystems), Dietmar Gaertner (Software AG), Marc Hadley (Sun Microsystems), Gerd Hoelzing (SAP AG), Oisin Hurley (IONA Technologies), Yin-Leng Husband (Hewlett Packard), John Ibbotson (IBM), Ryuji Inoue (Matsushita Electric), Kazunori Iwasa (Fujitsu Limited), Murali Janakiraman (Rogue Wave), Mario Jeckle (DaimlerChrysler Research & Technology), Mark Jones (AT&T), Anish Karmarkar (Oracle), Jacek Kopecky (Systinet), Yves Lafon (W3C), Michah Lerner (AT&T), Bob Lojek (Intalio), Brad Lund (Intel), Noah Mendelsohn (IBM), Jeff Mischkinsky (Oracle), Nilo Mitra (Ericsson), Jean-Jacques Moreau (Canon), Highland Mary Mountain (Intel), Don Mullen (Tibco), Masahiko Narita (Fujitsu Limited), Eric Newcomer (IONA Technologies), Henrik Frystyk Nielsen (Microsoft Corporation), David Orchard (BEA Systems), Andreas Riegg (DaimlerChrysler Research & Technology), Herve Ruellan (Canon), Marwan Sabbouh (Mitre), Miroslav Simek (Systinet), Simeon Simeonov (Macromedia), Nick Smilonich (Unisys), Lynne Thompson (Unisys), Patrick Thompson (Rogue Wave), Asir Vedamuthu (WebMethods), Pete Wenzel (SeeBeyond), Ray Whitmer (Netscape), Volker Wiechers (SAP AG), Stuart Williams (Hewlett Packard), Amr Yassin (Philips Research), Jin Yu (Martsoft).
Previous members were: Bill Anderson (Xerox), Mark Baker (Sun Microsystems), Philippe Bedu (Electricite de France), Olivier Boudeville (Electricite de France), Don Box (DevelopMentor), Tom Breuel (Xerox), Dick Brooks (Group 8760), Winston Bumpus (Novell), David Burdett (Commerce One), Charles Campbell (Informix Software), Alex Ceponkus (Bowstreet), Miles Chaston (Epicentric), David Clay (Oracle), David Cleary (Progress Software), Ugo Corda (Xerox), Fransisco Cubera (IBM), Ron Daniel (Interwoven), Glen Daniels (Allaire), Dug Davis (IBM), Ray Denenberg (Library of Congress), Mike Dierken (DataChannel), Andrew Eisenberg (Progress Software), Brian Eisenberg (DataChannel), John Evdemon (XMLSolutions), David Ezell (Hewlett Packard), Eric Fedok (Active Data Exchange), Daniela Florescu (Propel), Dan Frantz (BEA Systems), Michael Freeman (Engenia Software Corp), Scott Golubock (Epicentric), Rich Greenfield (Library of Congress), Martin Gudgin (DevelopMentor), Hugo Haas (W3C), Mark Hale (Interwoven), Randy Hall (Intel), Bjoern Heckel (Epicentric), Erin Hoffman (Tradia), Steve Hole (MessagingDirect Ltd.), Mary Holstege (Calico Commerce), Jim Hughes (Fujitsu Software Corp), Yin-Leng Husband (Compaq), Scott Isaacson (Novell), Eric Jenkins (Engenia Software), Jay Kasi (Commerce One), Jeffrey Kay (Engenia Software), Richard Koo (Vitria Technology Inc.), Jacek Kopecky (IDOOX), Alan Kropp (Epicentric), Julian Kumar (Epicentric), Peter Lecuyer (Progress Software), Tony Lee (Vitria Technology Inc.), Henry Lowe (OMG), Matthew MacKenzie (XMLGlobal Technologies), Murray Maloney (Commerce One), Richard Martin (Active Data Exchange), Noah Mendelsohn (Lotus Development), Alex Milowski (Lexica), Kevin Mitchell (XMLSolutions), Ed Mooney (Sun Microsystems), Dean Moses (Epicentric), Rekha Nagarajan (Calico Commerce), Raj Nair (Cisco), Mark Needleman (Data Research Associates), Art Nevarez (Novell), Mark Nottingham (Akamai Technologies), Conleth O'Connell (Vignette), David Orchard (Jamcracker), Kevin Perkins (Compaq), Jags Ramnaryan (BEA Systems), Vilhelm Rosenqvist (NCR), Waqar Sadiq (Vitria Technology Inc.), Rich Salz (Zolera) Krishna Sankar (Cisco), George Scott (Tradia), Shane Sesta (Active Data Exchange), Lew Shannon (NCR), John-Paul Sicotte (MessagingDirect Ltd.), Simeon Simeonov (Allaire), Aaron Skonnard (Developmentor), Soumitro Tagore (Informix Software), James Tauber (Bowstreet), Jim Trezzo (Oracle), Randy Waldrop (WebMethods), Fred Waskiewicz (OMG), David Webber (XMLGlobal Technologies), Yan Xu (DataChannel), Susan Yee (Active Data Exchange).
We also wish to thank all the people who have contributed to discussions on xml-dist-app@w3.org.