Introduction to WS-Addressing

by Beth Linker
01/31/2005

Abstract

The WS-Addressing specification defines a standard for incorporating message addressing information into web services messages. WS-Addressing provides a uniform addressing method for SOAP messages traveling over synchronous and/or asynchronous transports. Additionally, it provides addressing features to help web service developers build applications around a variety of messaging patterns beyond the typical exchange of requests and responses. This article introduces WS-Addressing, describes its components, and explores its potential value for developers.

Introduction

The web services specifications known as WS-* are primarily the result of work by major technology vendors such as Microsoft, Sun, BEA, IBM, and SAP. Some of these specifications, including WS-Addressing, are being developed under the umbrella of the World Wide Web Consortium (W3C). The WS-Addressing specification, accepted by W3C as a member submission in August 2004, provides a standard for representing message addressing information in web services messages and service descriptions.

The W3C's Web Services Addressing Working Group is in the process of revising and finalizing the WS-Addressing specification. We can definitely expect to see further changes in the specification because a number of issues are still being resolved. For example, in January 2005 the working group agreed to eliminate the "reference properties" feature described below, but that decision has not yet been reflected in a published draft. Despite the ongoing changes, the central ideas in WS-Addressing should remain stable, so it's a good time for developers to take a look.

All of the WS-* specifications are designed on top of SOAP. They define XML schemas for use within the header block of a SOAP message. By design, dependencies between the WS-* specifications are very limited. This encourages developers to use only what they need. WS-Addressing is independent of the other WS-* specifications but can be used in conjunction with them. For example, an application might use WS-Addressing to identify a message's source and destination and also use WS-Security to authenticate the source to the destination.

WS-Addressing also has a tenuous connection to the Web Services Description Language 1.1 (WSDL). It extends and incorporates some concepts from WSDL, but there is no explicit dependency between the two. Web services developers can use either or both, depending on their needs. WSDL provides a vocabulary for describing a service in both abstract terms (messages sent and received) and concrete terms (transport and wire format). WS-Addressing makes use of WSDL's "service" and "port" concepts, as described below.

WS-Addressing is currently published as three separate specifications, WS-Addressing Core, WS-Addressing SOAP Binding, and WS-Addressing WSDL Binding. The core specification describes abstract properties, and the binding documents explain how to represent those properties in SOAP and WSDL respectively. The core/bindings breakdown is a common one in web services specifications. Here, the core specification is generally of more interest to application developers than the binding documents because web services libraries and developer tools typically encapsulate the details of the binding.

WS-Addressing's Purpose

SOAP does not provide a standard way to specify where a message is going, how to return a response, or where to report an error. Those details have historically been left up to the transport layer. For example, when a standard SOAP request is sent over HTTP, the URI of the HTTP request serves as the message's destination. The message response is packaged in the HTTP response and received by the client over the HTTP connection. When a SOAP request message is sent asynchronously through JMS, a destination for responses might be specified in the JMS message headers, incorporated into the message body, or left up to the service implementation.

Addressing at the transport level is sufficient for many existing services, but it has been a limiting factor in the development of others. WS-Addressing defines standard ways to route a message over multiple transports or direct a response to a third party. For example, a client application might send a request over JMS and ask to receive the response through e-mail or SMS. To enable these kinds of applications, WS-Addressing incorporates delivery, reply-to, and fault handler addressing information into a SOAP envelope. The following example illustrates a typical SOAP message using WS-Addressing:

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope"

                xmlns:wsa="http://www.w3.org/2004/12/addressing">

    <S:Header>

        <wsa:MessageID>

            http://example.com/SomeUniqueMessageIdString

        </wsa:MessageID>

        <wsa:ReplyTo>

            <wsa:Address>http://myClient.example/someClientUser</wsa:Address>

        </wsa:ReplyTo>

        <wsa:FaultTo>

            <wsa:Address>http://myserver.example/DemoErrorHandler</wsa:Address>

        </wsa:FaultTo>

        <wsa:To>http://myserver.example/DemoServiceURI</wsa:To>

        <wsa:Action>http://myserver.example/DoSomething</wsa:Action>

    </S:Header>

    <S:Body>

         <!-- The message body of the SOAP request appears here -->

    </S:Body>

</S:Envelope>

WS-Addressing also defines a standard for including service-specific attributes within an address for use in routing the message to a service or for use by the destination service itself. These attributes are particularly useful for the creation of stateful web services, which are services that can receive a series of requests from a particular client and remember some state information between requests.

Core Constructs

WS-Addressing introduces two new constructs for your web services vocabulary: endpoint references and message addressing properties. "Endpoint" is an established term for a destination at which a web service can be accessed. Endpoint references are a new model for describing these destinations. Message addressing properties, which may include one or more endpoint references, provide a context for that destination information.

A postal mail envelope provides a good non-technical analogy: the destination address is written in the center of the envelope, and a return address is provided on the back. The specific format of an individual address (Name, Street, City/State/Zip Code in the U.S.) is analogous to an endpoint reference. The layout of addresses on the envelope is analogous to WS-Addressing's message addressing properties.

Anatomy of an Endpoint Reference

Endpoint references are defined as a complex type in the WS-Addressing schema. The endpoint reference type contains an address (a URI), reference properties, reference parameters, a port type, a service name, and policy elements (defined by the WS-Policy specification). The only required element of an endpoint reference is the address, so the simplest possible endpoint reference is essentially a URI:

<wsa:Address>http://ws.example.com/myservice</wsa:Address>

The other elements of an endpoint reference are all optional, making it easy to use only what you need. The port type and service name elements are very similar to their WSDL counterparts. WSDL defines a port type as an identifying name attached to an abstract set of operations. A binding specifies concrete inputs and outputs for the port type. A port of that type represents a deployment of the binding at a specific address. A service is a named collection of ports. As in WSDL, the port type and service name are QNames (qualified names) in WS-Addressing. The port type and service name in a WS-Addressing endpoint reference are meant to provide compatibility with WSDL rather than to replace it entirely.

A significant aspect of an endpoint reference is the ability to attach data from your own XML namespace via reference properties or reference parameters. Both of these elements are collections of properties and values that you can use to incorporate elements from your own XML namespace (or any XML namespace) into the endpoint reference. The key distinction between a reference property and a reference parameter is not the format but the intended usage.

A reference property is used to identify the endpoint at which a service is deployed. Two endpoint references that share a URI but specify different reference property values represent two different services. Reference properties are used to dispatch a request to the appropriate service. For example, one might deploy two different versions of a service and have requests specify a target version in their reference parameters. When a service receives a request and fulfills it, its behavior should not vary in response to the reference properties.

In contrast, reference parameters are meant to identify resources managed by a particular service. Reference parameters tell a service which resources to handle. They do not identify the service. Two endpoint references with different reference parameters do refer to the same service.

The following example shows an endpoint reference for a service that provides weather forecast information to the general public with more detailed information available for premium customers. The service's URI is specified in the Address element. A reference property indicates that the request is for the basic version of the service. A reference parameter specifies the city for which we're requesting a forecast:

<wsa:EndpointReference xmlns:wsa="..." xmlns:example="...">

   <wsa:Address>http://example.com/weather</wsa:Address>

   <wsa:ReferenceProperties>

       <example:ServiceLevel>Basic</example:ServiceLevel>

   </wsa:ReferenceProperties>

   <wsa:ReferenceParameters>

       <example:CityCode>NYC</example:CityCode>

   </wsa:ReferenceParameters>

</wsa:EndpointReference>

Message Addressing Properties

As explained above, endpoint references are used within message addressing properties. The message addressing properties define the full set of addressing information that can be attached to a SOAP message. Most of the fields are optional; the only required fields are the To and Action fields, each of which specifies a URI. In an HTTP request, these would be the same URI.

In a non-HTTP request, the To URI may differ from the Action URI. The request is delivered to the To URI. The Action URI indicates the action to be taken. The Action URI should represent a service corresponding to a WSDL port type (see above). For example, a request sent by e-mail or SMS may go to a destination that is not represented by a WSDL port type. The separation of the To URI and the Action URI allows for lots of flexibility in configuring web service destinations. For example, an e-mail address might receive requests for multiple services, all identified by their Action URI values. The To URI specifies the "where" and the Action URI specifies the "what": 

<!-- Message 1 -->

<wsa:To>mailto:ws@example.com</wsa:To>

<wsa:Action>http://example.com/aservice</wsa:Action>

// ...

<!-- Message 2 -->

<wsa:To>mailto:ws@example.com</wsa:To>

<wsa:Action>http://example.com/anotherservice</wsa:Action>

// ...

In addition to the required To and Action URIs, the message addressing properties include several optional elements. The ReplyTo and FaultTo elements are fairly self-explanatory. A ReplyTo endpoint must be specified only when the sender expects a response, but it can be used to route that response to any valid endpoint. FaultTo is always optional and routes SOAP fault messages to specified endpoint references. Additionally, consumers of a service can use a From endpoint reference element to identify themselves to the service. Explicitly separating the message source endpoint, expected reply endpoint, and fault handling endpoint helps WS-Addressing support a variety of messaging models beyond the simple request/reply interactions we typically associate with web services.

When a reply is expected, whether it is expected by the sender or by a third endpoint specified in the ReplyTo header, a MessageId element must also be present. The message ID is a unique URI. Because web services can be used over unreliable transports, it is possible that an endpoint will receive duplicate copies of a message. The message ID can be used to avoid processing the same message twice.

When a service receives a message addressed using WS-Addressing, it will also include WS-Addressing headers in the reply message. The message ID of the original message becomes a RelatesTo element in the reply's address. At present, the only supported relationship type is "Reply." If a client is sending multiple web services requests and receiving asynchronous responses, possibly over different transports, the RelatesTo element provides a standard way to associate incoming replies with their corresponding requests.

WS-Addressing for Developers

Developer tools for working with WS-Addressing are on the way but are not yet widely available. If your existing web services applications depend on WebLogic Workshop, Apache Axis, or another tool that generates a web services interface for a Java API, then you may need to wait until those environments have expanded to incorporate WS-Addressing. Because WS-Addressing is driven by major enterprise vendors, new WS-Addressing tools for developers should emerge throughout 2005.

For applications that use web services for straightforward remote HTTP access to objects, WS-Addressing is not a revolution. Because an HTTP request and response occur synchronously over a single HTTP connection, addressing does not add very much excitement. BEA's Dave Orchard, a WS-Addressing co-author, recently wrote a blog entry exploring the possibilities for WS-Addressing and HTTP. Even to the authors of WS-Addressing, the value of WS-Addressing over HTTP isn't necessarily apparent at this point. If your web services are only serving HTTP clients, the "use what you need" nature of the WS-* specifications makes it easy to ignore WS-Addressing until it becomes relevant.

WS-Addressing offers a lot more to developers who are using web services over asynchronous transports. Using a consistent addressing model across multiple transports could simplify some integration issues and help developers implement systems where dispatchers route requests to one of several related services using endpoint references. As mobile computing becomes more important, asynchronous web services will be very useful for supporting mobile clients with limited network access. A generic model for addressing can help minimize the effort required to expose a web service to a variety of asynchronous clients. As mentioned above, those of us who focus on application development may need to wait for vendors to roll out appropriate tools before we can take advantage of some of these opportunities.

Like the other emerging web services specifications, the value of WS-Addressing has yet to be proven in the field. If it turns out to be a bust, it would certainly not be the first time major vendors backed an initiative that lacked staying power. Whether WS-Addressing looks like the next big thing or the next short-lived fad, this article has hopefully given you some insight into what the specification says and some of the changes it aspires to enable.

Additional Reading

Beth Linker is a software engineer specializing in enterprise Java and web services. Based in Boston, MA, she is a software architect at Iron Mountain Digital.