Update 2004-08-10: see "WS-Addressing Specification Presented to W3C as a Member Submission."

Update 2004-03-30: A revised version of the WS-Addressing specification was announced by Microsoft on March 30, 2004. This specification "has been improved based on community feedback and multi-vendor implementation experience. Changes include an improved definition of request-reply and a new WSDL binding and fault codes." See the news item "Updated Releases of the WS-Addressing and WS-MetadataExchange Specifications."

Apache Addressing is an open source implementation of the Web Services Addressing (WS-Addressing) specification. It is built on top of Apache Axis, 'The Next Generation SOAP'. The announcement for Apache Addressing as an Apache Web Services Project is one evidence among several of the growing recognition that WS-Addressing is a key specification for Web Services messaging.

WS-Addressing "defines two constructs that convey information that is typically provided by transport protocols and messaging systems in an interoperable manner. These constructs normalize this underlying information into a uniform format that can be processed independently of transport or application. The two constructs are endpoint references and message information headers." An endpoint reference contains a Net address and an optional collection of reference properties, functioning as a "generic URI." The goal of the specification is to provide "transport-neutral mechanisms to address Web services and messages, enabling messaging systems to support message transmission through networks that include processing nodes such as endpoint managers, firewalls, and gateways in a transport-neutral manner."

Produced as a private WS-* specification by BEA, IBM, and Microsoft, WS-Addressing was published in March 2003 and revised in May 2003. It is being implemented in WSE (Web Services Enhancements), a supported add-on to Microsoft Visual Studio .NET and the Microsoft .NET Framework. WS-Addressing normatively references WS-Policy and is referenced by a growing number of WS-* specifications.

Bibliographic Information

Web Services Addressing (WS-Addressing). 13 March 2003. Copyright (c) 2002-2003 by BEA Systems Inc., International Business Machines Corporation, Microsoft Corporation. Authors: Adam Bosworth (BEA), Don Box (Microsoft, Editor), Erik Christensen (Microsoft), Francisco Curbera (IBM, Editor), Donald Ferguson (IBM), Jeffrey Frey (IBM), Chris Kaler (Microsoft), David Langworthy (Microsoft), Frank Leymann (IBM), Steve Lucco (Microsoft), Steve Millet (Microsoft), Nirmal Mukhi (IBM), Mark Nottingham (BEA), David Orchard (BEA), John Shewchuk (Microsoft), Tony Storey (IBM), and Sanjiva Weerawarana (IBM). 14 pages. Note: this PDF document contains the revised/updated version, ca. May 19/23, 2003. With XML Schema.

Acknowledgements are provided to: Michael Coulson, Microsoft; Giovanni Della-Libera, Microsoft; Christopher Ferris, IBM; Tom Freund, IBM; Steve Graham, IBM; Maryann Hondo, IBM; Efim Hudis, Microsoft; John Ibbotson, IBM; Gopal Kakivaya, Microsoft; Al Lee, Microsoft; Anthony Nadalin, IBM; Martin Nally, IBM; Henrik Frystyk Nielsen, Microsoft; Jeffrey Schlimmer, Microsoft; Keith Stobie, Microsoft.

The WS-Addressing specification makes normative use of WS-Policy. As of March 2004, several other (WS-*) specifications made (normative) reference to WS-Addressing. Examples:

• Web Services Eventing (WS-Eventing)
• Web Services Dynamic Discovery (WS-Discovery)
• Web Services Reliable Messaging Protocol (WS-ReliableMessaging)
• Web Services Business Process Execution Language [BPEL4WS]
• Web Services Resource Framework specifications, especially WS-RenewableReferences
• Web Services Notification Framework specifications, including Web Services Base Notification (WS-Base Notification) and Web Services Brokered Notification (WS-BrokeredNotification)
• Web Services Metadata Exchange (WS-MetadataExchange)
• Web Services Policy Framework specifications version 1.1, including WS-PolicyAttachment and WS-Policy
• Web Services Distributed Management draft specifications, including Management of Web Services (WSDM-MOWS) and Management Using Web Services (MUWS)

WS-Addressing Overview

Web Services Addressing (WS-Addressing) defines two constructs that convey information that is typically provided by transport protocols and messaging systems in an interoperable manner. These constructs normalize this underlying information into a uniform format that can be processed independently of transport or application. The two constructs are endpoint references and message information headers.

A Web service endpoint is a (referencible) entity, processor, or resource where Web service messages can be targeted. Endpoint references convey the information needed to identify/reference a Web service endpoint, and may be used in several different ways: endpoint references are suitable for conveying the information needed to access a Web service endpoint, but are also used to provide addresses for individual messages sent to and from Web services. To deal with this last usage case this specification defines a family of message information headers that allows uniform addressing of messages independent of underlying transport. These message information headers conveys end-to-end message characteristics including addressing for source and destination endpoints as well as message identity.

Both of these constructs are designed to be extensible and re-usable so that other specifications can build on and leverage endpoint references and message information headers.

The WS-Addressing XML Namespace URI is http://schemas.xmlsoap.org/ws/2003/03/addressing. Though the choice of namespace prefix "is arbitrary and not semantically significant," the prefix used with the WS-Addressing namespace 'http://schemas.xmlsoap.org/ws/2003/03/addressing' in the specification is wsa.

The namespace for WS-Policy is also used in the WS-Addressing specification. Specification Section 2.1 'Information Model for Endpoint References' clarifies that abstract properties of an endpoint reference include [policy] : wsp:policy (0..unbounded), viz., "A variable number of XML policy elements as described in WS-Policy describing the behavior, requirements and capabilities of the endpoint. Policies may be included in an endpoint to facilitate easier processing by the consuming application, or because the policy was dynamically generated." For WS-Policy references, see Web Services Policy Framework."

WS-Addressing is defined in terms of the W3C XML Information Set. WS-Addressing is conformant to the SOAP 1.2 processing model; SOAP 1.2 is not a requirement for using the constructs defined in this specification. WS-Addressing is also designed to be able work with WSDL 1.1 described services. The examples in this specification use an XML 1.0 representation but this is not a requirement.

Model and Syntax for Endpoint References: This specification introduces a new description element type, the endpoint reference, with the intent of supporting a set of dynamic usage patterns not currently appropriately covered by WSDL 1.1. In particular, this specification intends to facilitate the following usage scenarios:

• Dynamic generation and customization of service endpoint descriptions.
• Identification and description of specific service instances that are created as the result of stateful interactions.
• Flexible and dynamic exchange of endpoint information in tightly coupled environments where communicating parties share a set of common assumptions about specific policies or protocols that are used during the interaction.

To support these scenarios, we define a lightweight and extensible mechanism to dynamically identify and describe service endpoints and instances. Because of the current limits of the WSDL 1.1 extensibility model, the WSDL 1.1 service and port elements cannot be used to cover the use cases listed above. Endpoint references logically extend the WSDL description model (e.g., portTypes, bindings, etc.), but do not replace it. Endpoint references will be used instead of WSDL <service/> elements in the following cases:

• Specific instances of a stateful service need to be identified or its instance specific configuration details need to be transmitted.
• A lightweight, self-contained description of a service endpoint needs to be communicated. In particular, this may be necessary when the details of the endpoint configuration are already shared by the communicating parties, but specific policy information needs to be added or updated, typically as a result of a dynamic configuration process.

Endpoint references compliment and do not replace the WSDL/1.1 <wsdl:service> element. We expect solutions built on WSDL/1.1 to continue to utilize a service element. Moving forward we anticipate that endpoint references and WSDL will evolve coherently. The endpoint references may link to service elements in WSDL/1.1, and support additional scenarios in which the WSDL information is not known by a party processing a message. These scenarios may include dynamic messaging or limited capability message processors..." [adapted from spec Sections 1-2]

WS-Addressing from 'The Basics — Transports and Messaging'

From "Secure, Reliable, Transacted Web Services: Architecture and Composition," by IBM and Microsoft:

"Messages and responses both go somewhere and come from somewhere. WS-Addressing provides an interoperable, transport independent approach to identifying message senders and receivers. WS-Addressing also provides a finer grain approach to identifying specific elements within a service that send or should receive a message.

Today most systems using Web services encode the destination for a Web service message with a URL that is placed in the HTTP transport. The destination for the response is determined by the return transport address. This approach builds on the basic browser-server model of HTTP.

Using today's approach, the source and destination information are not part of the message itself. This can cause several problems. The information can be lost if a transport connection terminates (for example, if the response takes a long time and the connection times out) or if the message is forwarded by an intermediary such as a firewall.

WS-Addressing provides a mechanism to place the target, source and other important address information directly within the Web service message. In short, WS-Addressing decouples address information from any specific transport model.

In many scenarios messages are targeted directly to a service and the addressing information in the message can be described simply using a URL. But in practice, we often find that messages are targeted to specific elements or resources within a service. For example, a coordination service might be coordinating many different tasks. The coordinator needs to associate most incoming messages with a specific task instance that it manages and not the coordination service itself.

WS-Addressing provides a simple yet powerful mechanism called an endpoint reference for addressing entities managed by a service. While such information could be encoded in an ad-hoc manner within the URL of the service, the endpoint references provides a standard XML element that enables a structured approach to encoding this fine-grained addressing.

The combination of fine-grain control over addressing coupled with the transport-neutral encoding of the message source and destination enables Web service messages to be sent across a range of transports, through intermediaries, and it enables both asynchronous and extended duration communication patterns.

WS-Addressing also enables a sender to indicate where a response should go in a transport-independent manner. The response to a message may not necessarily go to the sender. In HTTP for example, without WS-Addressing it is impossible to specify that the response should be sent elsewhere.

These enhancements to the messaging model enable Web services to be used to support many business scenarios. For example, certain banking tasks require human review for approval at certain steps. There are usually many active instances of the task at any point in time. WS-Addressing provides a general mechanism to associate incoming or outgoing messages with specific tasks. The mechanism that the service uses is transparent to those using the service through an endpoint reference..." [excerpted]

WS-Addressing and the WS-Resource Framework

The WS-Addressing specification plays a key role in the Web Services Resource Framework and Web Services Notification Framework. Excerpts from the document Modeling Stateful Resources with Web Services Version 1.1 (03/05/2004), which describes WS-Addressing as "an XML serialization and standard SOAP binding for representing network wide 'pointers' to services":

"In the WS-Resource approach, we model state as stateful resources and codify the relationship between Web services and stateful resources in terms of the implied resource pattern, a set of conventions on Web services technologies, in particular WS-Addressing...

We define the term implied resource pattern to describe a specific kind of relationship between a Web service and one or more stateful resources. The implied resource pattern refers to the mechanisms used to associate a stateful resource with the execution of message exchanges implemented by a Web service. The term implied is used because the stateful resource associated with a given message exchange is treated as implicit input for the execution of the message request. By implicit, we mean to say that the requestor does not provide the stateful resource identifier as an explicit parameter in the body of the request message. Instead, the stateful resource is implicitly associated with the execution of the message exchange. This can occur in either a static or a dynamic way...

We use the term pattern to indicate that the relationship between Web services and stateful resources is codified by a set of conventions on existing Web services technologies, in particular XML, WSDL, and WS-Addressing...

A WS-Addressing endpoint reference is an XML serialization of a network-wide pointer to a Web service. This pointer may be returned as a result of a Web service message request to a factory to create a new resource or, alternatively, from the evaluation of a search query on a registry of resources, or as a result of some application-specific Web service request. WS-Addressing standardizes the endpoint reference construct used to represent the address of a Web service deployed at a given network endpoint. An endpoint reference may contain, in addition to the endpoint address of the Web service, other metadata associated with the Web service such as service description information and reference properties, which help to define a contextual use of the endpoint reference. The reference properties of the endpoint reference play an important role in the implied resource pattern.

Note that other patterns for enabling access to stateful resources are possible. For example, a Web service could maintain the resource identity as static service state, thus obviating the need to pass that identity in the WS-Addressing endpoint reference. This design choice implies a one-to-one mapping from Web service endpoints to stateful resources and thus a need for a unique Web service endpoint for each stateful resource..." [from Section 3.2; see also details and illustrations in Section 3.3, "WS-Resource and WS-Addressing."

The WS-RenewableReferences specification "describes how a WS-Addressing endpoint reference can be decorated with information on how a new version of an endpoint reference can be retrieved by a requestor when an endpoint reference becomes invalid. This specification is a work in progress..."