Web Services Technical Articles

WS-Addressing Additions and Updates

April 2004

Authors

Omri Gazitt
David Langworthy

Abstract

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. Additions
1.1 WSDL Binding
1.2 Fault Codes
1.3 Request/Reply
2. Changes and Clarifications
2.1 "Response" to "Reply"
2.2 Recipient
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. Examples
4.1 One Way
4.2 Fault
5. References

1. Additions
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.

1.1 WSDL Binding

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.

1.2 Fault Codes

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.

1.3 Request/Reply

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.

2. Changes and Clarifications

The specification includes several changes and clarifications to the prior version. This
section describes those changes and the reasoning behind them.
2.1 "Response" to "Reply"

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.

2.2 Recipient

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.

2.3 MessageID and Retransmission

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.

2.4 The Anonymous URI

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.

3. Implementation Considerations
Our experience implementing WS-Addressing led to several observations. We summarize the
most significant in this section.

3.1 Comparing Message ID and Action

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.

3.2 Comparing EndpointReferences

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.

3.3 Attributes and Elements in ReferenceProperties

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.

4. Examples
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.

4.1 One Way

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.

Copy
<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

[action] http://business456.com/mail/NewMail

4.2 Fault

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.

Copy
<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>

[destination] http://business456.com/client1

[message id] uuid:aaaabbbb-cccc-dddd-eeee-wwwwwwwww

[relationship] (wsa:Reply, uuid:aaaabbbb-cccc-dddd-eeee-ffffffffffff)

[action] http://schemas.xmlsoap.org/ws/2004/03/addressing/fault

[code] S:Receiver

[subcode] wsa:EndpointUnavailable

[reason] The endpoint is unable to process the message at this time.

[detail] wsa:RetryAfter>3600000</wsa:RetryAfter>

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.

5. References
[WS-Addressing]
"Web Services Addressing," BEA Systems, IBM, Microsoft, March 2004.
[WS-Policy]
"Web Services Policy Framework," Microsoft, IBM, BEA Systems, SAP, 18 December 2002.
[WSDL]
"Web Services Description Language (WSDL) 1.1," Microsoft, IBM, March 2001.
[WSRM]
"Web Services Reliable Messaging," BEA Systems, Microsoft, IBM, TIBCO Software, March
2004.