SOAP introduces an extensible message format and a common processing model with the purpose of enabling different protocols and interaction patterns. Other specifications define, in a modular, composeable way, the additional artifacts and conventions required to support specific behaviors and protocols. First and foremost, mechanisms must be provided to ensure that messages are correctly delivered to the appropriate destination, or service endpoint. Web Services Addressing defines these mechanisms.
To provide these mechanisms, it’s necessary to resolve at least two different problems. The first is how to identify Web service endpoints. Before this chapter can begin to discuss how the Web services infrastructure will direct messages to their destinations, one must understand how to represent such “destinations” using a certain XML dialect. This problem is more subtle than it might appear at first sight, when it’s approached from a Web-only perspective, as opposed to a Web services or service-oriented perspective. That’s because of the rich and dynamic nature of Web service interactions as compared to traditional Web requests. The second problem is how to communicate these endpoint identifiers (or “endpoint references”) in the course of a Web services exchange. For example, how to encode endpoint references in a SOAP message as SOAP headers, and what is the precise meaning and processing model for those endpoint references? Here, again, the rich nature of the service-oriented interaction model calls for careful design.
The goal of the WS-Addressing specification is to provide the means to identify a Web service endpoint and a way to use such identifiers in SOAP messages for the delivery and exchange of messages between Web service providers and Web service requesters. Together, these two mechanisms define a simple yet powerful solution to the problem of how to address a Web service endpoint.
In a first approach, one could build a simple solution to the addressing problem by using the mechanisms that the current Web architecture provides to identify and address Web “resources” (that is, Web pages and any other Web-accessible resource). This would essentially mean borrowing the addressing model used by the HyperText Transport Protocol (HTTP). A uniform resource identifier (URI) identifies a Web resource, and the HTTP protocol clearly defines how to use these identifiers to direct requests to the resource. This is a powerful and well-understood mechanism that supports the operation of the Web. Following this model, one could assign a unique URI to each service endpoint and use HTTP headers to encode any additional information required in the course of the interaction. There are, however, important differences between traditional Web interactions and Web services interactions, which render the URI-HTTP addressing and interaction model insufficient as a solution for the Web services addressing problem. Following are some important characteristics of Web services interactions to take into account when considering the addressing problem:
Access to services is not limited to a single protocol. SOAP messages might be, and are likely to be, carried over protocols different from HTTP. These protocols can include proprietary messaging protocols. Several different protocols may even be used in the course of a single service interaction.
Service interactions are not restricted to simple synchronous request-response exchanges. Typically, they involve asynchronous messages, too, and they are rich in quality of service properties, such as security and transactions.
Web services support business interactions that are typically long running and stateful. That is, they comprise several related message exchanges over a potentially long period.
These characteristics are a direct reflection of the kind of real-world problems that Web services intend to address. SOAP messages that one enterprise sends to another are typically carried over different transport protocols along their path. Initially sent by the originating application (possibly using a proprietary protocol), these messages are transmitted over HTTP between the two enterprises and then delivered to the target application, possibly over a third protocol. Similarly, asynchronous interactions (over e-mail or other messaging protocols), are a fact of the day-to-day interaction between businesses and their customers. Existing messaging protocols already define a specific mechanism to support the asynchrony of the interactions. For example, they provide reply-to addresses for follow-up correspondence and allow for the identification of messages so that future responses can be correlated to the original message.
Note also that when business interactions are automated, quality of service guarantees become essential. For example, it is necessary to ensure that transmission errors and application failure situations are appropriately addressed, unauthorized access is prevented, confidentiality of the interaction adequately protected, etc. In short, quality of service guarantees a fundamental aspect of the interaction with a service endpoint, to an extent not found in regular Web interactions.
The stateful character of business interactions is particularly important. Service and business interactions usually comprise several interrelated message exchanges with each of the involved parties. These messages are logically related and are processed within a common context, even if they are not exchanged consecutively. The term used to describe this type of interaction is stateful. Individual applications can manage themselves the stateful character of a service interaction, but a cleaner and more efficient model results if the basic interaction framework directly embeds support for stateful interactions.
URIs and the HTTP protocol have proven their value in supporting today’s Web. However, central as they are to the architecture of the Web, they were not designed to support rich, flexible interactions, such as the ones just described. The requirement that can be derived from these characteristics is for an addressing mechanism that is protocol independent, well structured, aware of Web service metadata standards, and compatible with the SOAP messaging model.
WS-Addressing defines two fundamental concepts: endpoint references as a general-purpose way of encoding the addressing information needed to reach service endpoints, and message information headers to support the use of endpoint references in addressing and exchanging Web service messages.
An endpoint reference is a data structure that is defined to encapsulate all the information that is required to reach a service endpoint at runtime. A service endpoint in WS-Addressing is any potential source or destination of Web services messages. In view of this definition one can consider a Web Services Description Language (WSDL) port as a service endpoint. A WSDL port, however, is a descriptive abstraction that cannot (and, in fact, does not attempt to) capture the runtime character of service endpoints. The dynamic nature of service interactions often implies a more subtle relationship between the concepts of port and endpoint. In some cases, endpoints are dynamically generated and lack a WSDL description altogether. In other common situations, multiple endpoints share the same WSDL port representation, such as in the case of interactions with a service that provides the functions for processing multiple stateful resources. From the WS-Addressing point of view, a service endpoint maps to at most one WSDL port. As WSDL ports, endpoints can support at most one WSDL interface. Also, like WSDL ports (and with similar semantics), endpoints can have policies attached to them. On the other hand, endpoint references might carry additional runtime information (not present in the WSDL port definition) that is required to properly address and interact with an endpoint.
An endpoint reference contains two types of information: runtime information required for the interaction with the endpoint, and associated metadata. Runtime interaction information consists of three fields within an endpoint reference:
A mandatory address field (or “address property” in the terminology of the WS-Addressing specification)—This is the only mandatory required field; its value is a URI that represents the address at which the service endpoint can be reached.
A set of endpoint “reference properties”—These are information fields that are represented as XML elements; together with the endpoint address, they are used to help deliver messages to endpoint.
A set of “reference parameters”—These are information fields, also represented as XML elements, which are necessary to successfully interact with the endpoint but are not required to identify the endpoint when routing messages to it. The endpoint issuer provides them to facilitate the interaction.
The runtime information in the endpoint reference supports the routing of messages to the endpoint. The issuer of the endpoint reference (typically the service-side middleware infrastructure) defines the runtime information within the endpoint reference. This information is otherwise opaque to consumer applications; that is, a consumer application should not attempt to introspect or interpret the runtime information contained within an endpoint reference it receives. Applications (usually the service requester middleware) are simply required to include these fields in messages that are addressed to the endpoint according to the specific data representation and protocol used. In the case of SOAP, the WS-Addressing specification defines how these properties are incorporated as headers of a SOAP message. SOAP binding is discussed later in this chapter (Section 5.2.4).
In addition to runtime information, an endpoint reference can include metadata associated with the endpoint. The metadata helps consuming applications configure their interaction with the endpoint. It has three fields:
The qualified name of the port type that the endpoint supports. This is an optional field. It might be omitted either because it is undefined (that is, no WSDL port type definition of the interface of the endpoint is available) or because it is assumed that the consumer of the endpoint reference has this information available through some out-of-band mechanism.
The WSDL service name (a qualified name) and port name that provide the static representation of the endpoint. Again, this is an optional field.
Policies that are applicable to the endpoint, represented by an optional set of WS-Policy policy elements that need to be followed when interacting with the endpoint.
Following is an example of an endpoint reference:
<wsa:EndpointReference>
<wsa:Address>http://www.example.com/stq</wsa:Address>
<wsa:ReferenceProperties>
<exp:customer-id>xgtopsnlk-0001<exp:customer-id>
</wsa:ReferenceProperties>
<wsa:ReferenceParameters>
<exp:model-id>llp-11<exp:model-id>
</wsa:ReferenceParameters>
<wsa:PortType>tns:StockQuotePortType</wsa:PortType>
<wsa:ServiceName PortName="StockQuotePort">
tns:StockQuoteService
</wsa:ServiceName>
</wsa:EndpointReference>
Among the runtime information included in an endpoint reference, the address and reference properties determine the message destination and the expected behavior of the endpoint. Two endpoint references with identical addresses and sets of reference properties must be assumed to represent the same endpoint in the sense that both point to the same location and follow the same behavior. In particular, both endpoints support the same interfaces and the same protocol binding and comply with the same policies. Thus, two endpoint references with different reference parameters represent the same endpoint as long as their address and reference properties match.
The runtime consequence of this distinction is that when the reference properties of an endpoint reference change, one must assume that a different set of polices applies to the endpoint, and the runtime infrastructure should make sure it has updated information about the applicable policy set for the new endpoint. One can accomplish this, for example, by using the metadata exchange service, described later in this book (see Chapter 9, “Web Services Metadata Exchange”). A change in the reference parameters does not imply a change in the set of applicable policies.
WS-Addressing introduces a set of message headers to allow messages to be directed to service endpoints and to provide the information necessary to support a rich bidirectional and asynchronous interaction. WS-Addressing explicitly recognizes the basic forms of interaction supported in WSDL 1.1 (one-way messages and request-reply interactions) and describes how message headers are used and processed in those cases. However, the use of WS-Addressing message headers is not limited to the two interactions and can support more complex message interactions as well.
Only two message headers are required on every message: one to identify the destination of the message, and a second one to indicate how to process the message:
Note that the identification of the target endpoint relies on the values of the endpoint reference properties as much as on the “To” URI address. If reference properties appear in the endpoint reference, they must be present on messages that are targeted to the endpoint. The way they appear on the message depends on the specific serialization (encoding) of the message. The next section presents the encoding rules that apply to SOAP messages. Not all endpoint references contain reference properties, however.
The “Action” header of a message identifies the message’s intent. The content (body) of a message is described by a certain document type, typically an XML Schema definition, but this is not enough to uniquely identify its intent since one can use the same document type with different purposes. For example, one might use a “CustomerInformation” document in one interaction to create a new record in a customer database and to update an existing record in another. In both cases, the document that is contained in the body of the message is the same, but each message must be processed differently. The Action header contains a URI value that indicates how the sender of the message intended the message to be processed. In this example, messages that are sent as input to the “CreateRecord” and “UpdateRecord” operations contain the same document type but carry different URI values in the Action header. This allows the receiving side to decide how to deal with messages that arrive at the endpoint.
The value of the Action URI is naturally related to the WSDL operation to which the message is related. In fact, because the Action URI indicates the intent of an individual message, it is naturally mapped to each of the messages that appear in the definition of a WSDL operation, rather than to the operation itself. Therefore, the input, output, and possible fault messages of a WSDL operation typically are assigned distinct, unique Action URIs. WS-Addressing provides two mechanisms to assign these URIs to the messages of a WSDL operation—one explicit and another implicit. WS-Addressing defines an attribute in the WS-Addressing namespace, “wsa:Action”, which one can encode on the input, output, and fault elements of a WSDL operation definition to explicitly assign an Action value to them. The example that follows, from Section 3.3 of the WS-Addressing specification, shows how this is done.
<portType name="StockQuotePortType">
<operation name="GetLastTradePrice">
<input message="tns:GetTradePricesInput"
wsa:Action="http://example.com/GetQuote"/>
<output message="tns:GetTradePricesOutput"
wsa:Action="http://example.com/Quote"/>
</operation>
</portType>
To deal with WSDL documents that don’t explicitly assign Action values to messages and to relieve WSDL authors from the burden of creating and encoding Action URIs for all their WSDL operation messages, WS-Addressing defines an implicit encoding scheme. When no explicit statement is made about the value of the Action URI for a message, it is implicitly assumed that the value is derived from a combination of the target namespace of the WSDL document and the port type and message names (the reader should refer to the WS-Addressing specification for a detailed definition of the corresponding algorithm to use for that purpose). If, in the preceding example, all the wsa:Action attributes were removed (and assuming the target namespace given next), the Action values for the input and output messages would be set by default to the following values:
Target namespace: http://www.example.com/wsdl/stockquote Input message Action: http://www.example.com/wsdl/stockquote/StockQuotePortType/ GetLastTradePriceRequest Output message Action: http://www.example.com/wsdl/stockquote/StockQuotePortType/ GetLastTradePriceResponse
The “ReplyTo” header contains the endpoint to send reply messages. The reply message is required when the message is the request in a request-reply exchange; it is optional in other cases.
The “FaultTo” header (should there be one) contains the endpoint where fault messages should be sent. If “FaultTo” is absent, one may use the ReplyTo endpoint instead.
The “Source” endpoint indicates the endpoint that originated the message. The use of the Source header is optional in all cases, but it is useful in many situations, for example when no endpoint is explicitly provided to send replies to, or when it is different from the endpoint that originated the message. The Source header also allows the receiving endpoint to keep track of who is sending the message, regardless of who needs to receive the answer or whether there will be an answer at all.
Two additional headers are provided to allow defining relationships between individual messages.
The “MessageId” header contains a URI value that uniquely identifies the message that carries it. Message identifiers make it possible to reference individual messages and define relationships between them. The MessageId field is only required when the message is the request in a request-reply exchange.
The “RelatesTo” header contains a URI value that must be the MessageId of a previously exchanged message. It defines the current message relationship to the message that is being identified. The “RelationshipType” attribute in this header specifies what type of correlation between the two messages is being asserted.
The relationship type is represented by a qualified name. WS-Addressing defines one such relationship to be represented by the qualified name “wsa:Reply.” It indicates that the message is the reply to a prior request, as part of a request-reply message exchange. Other relationship types will be defined in the future to support more complex relationships between messages derived from other message exchange patterns.
To illustrate how these headers are used together, this chapter examines how a service endpoint manipulates headers in the course of a request-reply interaction and uses the endpoint references provided in an incoming message to direct the response to the appropriate target. Before going into that, however, it’s necessary to examine how to formulate a SOAP message addressed to an endpoint using the information contained in the endpoint reference.
WS-Addressing defines how to encode the fields of an endpoint reference as SOAP headers when directing a SOAP message to the endpoint. In the message one must only encode the runtime information from the endpoint reference:
The URI value of the Address field in the endpoint reference is copied as the value of the To header in the SOAP message.
Each reference property element is copied as an individual SOAP header.
Each reference parameter element is copied as an individual SOAP header.
The sender of the message (the “consumer” application for the endpoint reference) treats reference properties and parameters as opaque tokens and limits its manipulation to steps 2 and 3. On the receiving side, headers that originate from reference properties are extracted by the service middleware and used to route the message to the appropriate processing endpoints. Reference parameters are made available but are not required for routing. Even though reference properties are not identified as such on a SOAP message, they are always known to the receiving side, because the service middleware defines and encodes them when issuing the endpoint reference.
The relationship among the information in the endpoint reference, the WSDL definition, and the WS-Addressing message headers that appear in a SOAP message is illustrated in Figure 5-1.
Even though WS-Addressing can support many other message exchange patterns, the request-reply pattern is particularly prevalent. For that reason, the request-reply pattern is explicitly discussed in the WS-Addressing specification. The specification provides normative guidance for the encoding of the request and reply messages.
In the formulation of a request message, the ReplyTo and MessageID headers are mandatory. A ReplyTo header is naturally required when asynchronous responses are needed to indicate where to send the asynchronous reply. In the case of synchronous request-reply interaction, the reply message is sent back through the open channel used by the synchronous transport (typically HTTP) to deliver the request. WS-Addressing requires that the ReplyTo header also be included in synchronous request-reply interactions and mandates the encoding of an endpoint reference whose address URI is a predefined URI introduced by the specification to represent anonymous endpoints. Although the ReplyTo header is strictly unnecessary in this case, the resulting simplification has significant value. One of the consequences is to allow the service middleware on the receiving side to infer from the message headers whether a reply is expected, permitting more efficient processing of one-way requests. (For instance, one may close a connection as soon as it is determined that that no reply is expected.)
The presence of a message identifier supports correlating the asynchronous reply to the original request. Again, although it’s not strictly required in the synchronous case, the requirement provides a uniform model for all requests and simplifies the encoding at the requester side and processing at the provider side.
To formulate a reply, the endpoint must follow three mandatory steps:
Extract the ReplyTo endpoint reference and use its contents to address the new reply message. In the case of a SOAP message, the rules to map its contents of the endpoint reference to SOAP headers are the ones defined before: the Address field is copied into the To header, while all reference properties and parameters become additional SOAP headers.
The RelatesTo header must be included, and the message identifier of the request is copied as its value. This allows the correlation of the reply with the original request.
The RelationshipType field is set to a value of “wsa:Reply” indicating that the message is a response message to the one identified by the value of the RelatesTo header.
Figure 5-2 illustrates how rules map the information that is contained in the request message and the WSDL definition of the invoked operation into the reply message.
One interesting consequence of WS-Addressing and its normative support for request-reply interactions is the introduction of a more dynamic model for service interactions. Consider a service that, according to its WSDL service description, offers a request-reply operation over a synchronous protocol such as HTTP. Requesters who invoked the service would assume that the service returned its responses over the open HTTP channel. Assuming WS-Addressing compliance implies that requesters now have full control over where and how the service will send its response. If the requester wants to receive the response in the traditional way, a ReplyTo header with the anonymous URI address would be encoded. However, if the requester encoded a different endpoint reference in the ReplyTo header, the service provider would accordingly change its usual behavior. Upon receiving the request, it would close the incoming HTTP connection, open a new one to the address encoded in the ReplyTo, and use it to send its reply message. The result is that WS-Addressing endows the requester with an unprecedented degree of control over service behavior, which might seem to violate the WSDL binding contract of the service. Of course, after a service states its support for WS-Addressing, users of the services must assume conformance with the normative processing of request-reply patterns as part of the service behaviors.
As an example of the concepts just presented, assume that a service requester intends to invoke the “GetStockQuote” operation on the following endpoint reference:
<wsa:EndpointReference xmlns:exp="..." xmlns:tns="..."
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing">
<wsa:Address>http://www.example.com/stq</wsa:Address>
<wsa:ReferenceProperties>
<exp:customer-id>xgtopsnlk-0001<exp:customer-id>
</wsa:ReferenceProperties>
<wsa:ReferenceParameters>
<exp:model-id>llp-11<exp:model-id>
</wsa:ReferenceParameters>
<wsa:PortType>tns:StockQuotePortType</wsa:PortType>
<wsa:ServiceName PortName="StockQuotePort">
tns:StockQuoteService
</wsa:ServiceName>
</wsa:EndpointReference>
Using the information on the endpoint reference (Address, Reference Properties, and Reference Parameters) and the Action values encoded in the operation definition (as in the preceding example), a SOAP request message would be as follows (assuming that the port “StockQuotePort” provides a standard SOAP binding):
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
xmlns:exp="... ">
<S:Header>
<wsa:MessageID>uuid:aaaabbbb-cccc-dddd-eeee-ffffffffffff
</wsa:MessageID>
<wsa:ReplyTo>
<wsa:Address>
http://stq-services.com/requester
</wsa:Address>
</wsa:ReplyTo>
<wsa:To>http://www.example.com/stq</wsa:To>
<wsa:Action>http://example.com/GetQuote</wsa:Action>
<exp:model-id>llp-11<exp:model-id>
<exp:customer-id>xgtopsnlk-0001<exp:customer-id>
</S:Header>
<S:Body>
... <!—ticker symbol —>
</S:Body>
</S:Envelope>
Observe how the reference properties and parameters are serialized as SOAP headers in the SOAP envelope. The response from the endpoint is formulated using the values of the ReplyTo and MessageId headers in addition to the Action for the output message provided by the WSDL definition of the operation. It would be as follows:
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
xmlns:exp="... ">
<S:Header>
<wsa:RelatesTo> uuid:aaaabbbb-cccc-dddd-eeee-ffffffffffff
</wsa:RelatesTo>
<wsa:To>http://stq-services.com/requester</wsa:To>
<wsa:Action>http://example.com/Quote</wsa:Action>
</S:Header>
<S:Body>
... <!—quote —>
</S:Body>
</S:Envelope>
WS-Addressing is a base specification on which many of the most fundamental Web services protocols, described later in this book, must rely. For that reason, the stability of the specification is of paramount importance. No extensions or major modifications are expected. WS-Addressing has been submitted to the World Wide Web Consortium and will undergo a fast-track standardization process with the goal of producing a standard that is closely aligned with the current specification by the end of 2005.
The SOAP messaging model is the basic framework that supports runtime Web services interoperability. SOAP, however, does not define the mechanisms to unambiguously address messages to Web services endpoints, and it does not provide explicit support for rich service interactions such as asynchronous or stateful interactions. The WS-Addressing specification discussed in this chapter defines an Infoset representation of the information required to address service endpoints (the endpoint reference) and provides the rules and mechanisms needed to use that information (as headers in a SOAP message envelope) to support a rich set of services.