WS-Addressing Additions and Updates
This overview describes additions and changes in the WS-Addressing specification since original publication in 2003, and includes examples and implementation considerations not contained in the specification. (8 printed pages)
Table of Contents
1.1 WSDL Binding
1.2 Fault Codes
2. Changes and Clarifications
2.1 "Response" to "Reply"
2.3 MessageID and Retransmission
2.4 The Anonymous URI
3. Implementation Considerations
3.1 Comparing Message ID and Action
3.2 Comparing EndpointReferences
3.3 Attributes and Elements in ReferenceProperties
4.1 One Way
This publication of WS-Addressing [WS-Addressing] adds fault codes, a WSDL binding, and explicit direction on formulating the request-reply message exchange pattern. This section describes those additions and the reasoning behind them.
The Action in every message is the key to the application's intent. Web services endpoints described with WSDL require a mechanism to determine which Action to place on outbound messages (output). Correspondingly, WSDL processors require an inbound message be mapped to an input of an operation.
WS-Addressing defines two mechanisms to accomplish this, a default pattern and an explicit annotation. The default pattern allows services that use WSDL to adopt WS-Addressing without modification. Explicit annotation allows direct control over the Action to WSDL mapping. This control may be used to promote factoring and reuse in to a greater degree than natively supported in WSDL. It may also be used to allow a new version of a service to continue to accept messages from a prior version.
WS-Addressing requires an Action header on every message. This differs from the SOAP:Action header in the SOAP binding for WSDL [WSDL] that places an action URI on the request only. The specification clarifies this distinction and the binding provides a mechanism to define an action or construct a default action for both a request and a response.
WS-Addressing defines 5 new fault codes with explicit bindings to SOAP 1.1 and 1.2 fault messages. The fault messages are:
- Invalid Message Information Header
- Message Information Header Required
- Action Not Supported
- Destination Unreachable
- Endpoint Unavailable
The first two faults, Invalid Information Header and Message Information Header Required, deal with a malformed or missing WS-Addressing header. Action Not Supported is a special case in which the Action header is present and well formed, but the URI content does not match any action at the destination.
A processor generates the Destination Unreachable fault if it cannot determine a means to route the message to the destination. For example, this fault is generated in the case that the To header is malformed or does not exist. Any attempt to resend the message will not succeed. Endpoint Unavailable is different in that a route to the destination is known, but for some reason the endpoint is not currently available. A retransmission of the message in the future might succeed. Endpoint Unavailable returns an optional "RetryAfter" parameter to indicate how long the sender should wait until attempting another transmission.
The request-reply pattern is very common. The specification defines the explicit requirements for this message exchange pattern. In short, ReplyTo and MessageID are required on all requests, and RelatesTo is required on all responses. These headers may be used in other message exchange patterns, but must be used as defined in the request-reply pattern. The specification includes an example request and reply in WS-Addressing Section 3.2 and these are not repeated here.
The specification includes several changes and clarifications to the prior version. This section describes those changes and the reasoning behind them.
The prior revision of WS-Addressing used the terms "Response" and "Reply" interchangeably. To simplify explanations and improve consistency, the authors chose to use Reply exclusively. This resulted in a single change to the XML message format. For the RelationshipType attribute, Response changed to Reply. Since Response was the default and Reply is now the default, and no other RelationshipTypes are defined in the specification, this change should affect few messages in practice.
The prior revision of WS-Addressing defined a "Recipient" header that contained the entire endpoint reference (EPR) used to formulate a message. This same information is contained in the To header and the headers derived from reference properties. Packaging the information together offered efficiencies; however, our implementation experience proved that they were not significant. The header was removed to eliminate redundancy and simplify the processing model.
The purpose of the MessageID header is to assign each message a unique identity. This identity can be used for duplicate detection, message correlation, and many other purposes. The prior revision of WS-Addressing required that no message share the exact same MessageID content. This statement posed a problem for reliable messaging [WSRM], which retransmits the exact same application message to compensate for transient communication failures (dropped messages).
This revision relaxes the requirement slightly so that messages that have the same application intent may use the same MessageID. This definition allows MessageID to be used for correlation in the presence of retransmissions. Allowing the retransmission caused a minor security issue since a retransmission might be interpreted as a replay attack. The security considerations section describes how a timestamp may be used to resolve this issue.
WS-Addressing requires a ReplyTo header in every request message; however, in the case that requestor does not have a well-known identity, WS-Addressing Section 3 defines an anonymous URI for use in the ReplyTo Address. The prior revision forbade the use of this URI in any other circumstances. This caused a problem because the Address must become the To in the reply message. The intent of the restriction was to limit the use of the anonymous URI to this pattern. The specification now allows the anonymous URI to be used in the To of a reply and restricts its use elsewhere.
Our experience implementing WS-Addressing led to several observations. We summarize the most significant in this section.
Both MessageID and Action are defined to be URIs. In the general case, comparing URIs can be computationally expensive and may not always be feasible since URIs are opaque to endpoints other than their creator. It is difficult to determine whether two URIs with differing string encodings actually refer to the same resource other than at the location that created the URI. In the presence of aliasing, it is impossible. Fortunately, byte-for-byte comparison is extremely efficient and will never result in a false positive. That is, byte-for-byte comparison will never assert two URIs that actually refer to different resources as equal.
Based on this observation, an implementation can optimize critical path dispatch. Therefore, it is recommended that MessageID and Action content be generated in a uniform manner and be treated as a string.
It is frequently useful to determine if two EPRs refer to the same service. For example, it is common to cache metadata about a service so that it does not need to be retrieved on each usage. This issue is somewhat related to the issue of comparing MessageID and Action in the prior section. It differs in that an EPR consists of more than a URI.
Informally two EPRs refer to the same service if they have the same address and the same reference properties. Policy, PortType, and ServiceName do not contribute to EPR equivalence.
The reference properties in an EPR are promoted to SOAP headers in messages sent to the EPR. Therefore, the same care taken with headers should be taken with reference properties. For example, a SOAP 1.1 mustUnderstand="1" attribute on a reference property will become a SOAP 1.1 mustUnderstand="1" attribute on a header. This has the benefit of requiring that the endpoint understand the reference properties it created, which is a reasonable sanity check and useful in versioning. The drawback is it requires the EPR to use SOAP version 1.1.
A conflict may occur if an element already used in a message is included in reference properties. For example, including MessageID as a reference property will cause a conflict when the reference property is promoted to a header, and render the EPR useless because the specification forbids a message with two MessageID headers. Such a message should never be formed and, if received, should not be processed.
As described in the security considerations section, EPRs should be signed to prevent tampering and, as with all cryptographic signatures, a process must never sign data that does not reflect its intent.
The addressing specification provides an example of a request and a reply message pair. This section provides an example of a simple one-way message and a fault response.
The following is an example of the simplest possible WS-Addressing-compliant message. It is a one-way, anonymous message that contains only a To and an Action. An application that created such a message would have no requirement to identify or correlate the message. Nor would it require the identity of the source message processor be known.
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing"> <S:Header> <wsa:To>http://fabrikam123.com/Joe</wsa:To> <wsa:Action>http://business456.com/mail/NewMail</wsa:Action> </S:Header> <S:Body/> </S:Envelope>
This message has the following property values:
[destination] The URI http://fabrikam123.com/Joe
The following is an example of a SOAP 1.2 fault message. It is a reply to the request message in WS-Addressing Section 3.2 and is similar in several ways with the reply example in that section. The particular properties conveyed in the message are described below.
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing"> <S:Header> <wsa:MessageID> uuid:aaaabbbb-cccc-dddd-eeee-wwwwwwwwwww </wsa:MessageID> <wsa:RelatesTo> uuid:aaaabbbb-cccc-dddd-eeee-ffffffffffff </wsa:RelatesTo> <wsa:To S:mustUnderstand="1"> http://business456.com/client1 </wsa:To> <wsa:Action> http://schemas.xmlsoap.org/ws/2004/03/addressing/fault </wsa:Action> </S:Header> <S:Body> <S:Fault> <S:Code> <S:Value>S:Receiver</S:Value> <S:Subcode> <S:Value>wsa:EndpointUnavailable</S:Value> </S:Subcode> </S:Code> <S:Reason> <S:Text xml:lang="en"> The endpoint is unable to process the message at this time. </S:Text> </S:Reason> <S:Detail> <wsa:RetryAfter>3600000</wsa:RetryAfter> </S:Detail> </S:Fault> </S:Body> </S:Envelope>
[message id] uuid:aaaabbbb-cccc-dddd-eeee-wwwwwwwww
[relationship] (wsa:Reply, uuid:aaaabbbb-cccc-dddd-eeee-ffffffffffff)
[reason] The endpoint is unable to process the message at this time.
The first three properties ([destination], [message id], [relationship]) are exactly the same as the reply message in WS-Addressing Section 3.2. The [action] property is the default fault action defined in WS-Addressing Section 4. The remaining four properties ([code], [subcode], [reason], [detail]) are the values defined for the Endpoint Unavailable fault defined in Addressing 4.5. The content of RetryAfter is 3,600,000 milliseconds or one hour.
- "Web Services Addressing," BEA Systems, IBM, Microsoft, March 2004.
- "Web Services Policy Framework," Microsoft, IBM, BEA Systems, SAP, 18 December 2002.
- "Web Services Description Language (WSDL) 1.1," Microsoft, IBM, March 2001.
- "Web Services Reliable Messaging," BEA Systems, Microsoft, IBM, TIBCO Software, March 2004.