Web Services Addressing overview

Web Services Addressing (WS-Addressing) provides a standard framework for specifying the endpoints of a SOAP message. This framework is transport-neutral and improves the interoperability of web services that use different transport mechanisms. The WS-Addressing specification introduces message addressing properties and endpoint references.

Web Services Addressing (WS-Addressing) is a Worldwide Web Consortium (W3C) specification that improves interoperability between web services by defining a standard way to address web services and provide addressing information in SOAP messages. SOAP messages can be sent over a variety of transport mechanisms, including HTTP and WebSphere® MQ, each of which stores destination information for the message in a different way.

Existing CICS® web services that are deployed in a pipeline configured to use WS-Addressing can use the default WS-Addressing settings without requiring any changes. To take full advantage of the WS-Addressing capabilities, use the WS-Addressing API commands. The WS-Addressing implementation supports one SOAP fault for each WSDL operation.

Message addressing properties

Message addressing properties (MAPs) are a set of well defined WS-Addressing properties that can be represented as elements in SOAP headers. MAPs provide a standard way of conveying information, such as the endpoint to which message replies must be directed, or information about the relationship that the message has with other messages. The MAPs that are defined by the WS-Addressing specification are summarized in the following table.
Table 1. Message addressing properties defined by the WS-Addressing specification
Abstract WS-Addressing MAP name SOAP WS-Addressing MAP name MAP content type Multiplicity Description
[action] <wsa:Action> xs:anyURI 1..1 An absolute URI that uniquely identifies the semantics of the message. This value is required.
[destination] <wsa:To> xs:anyURI in the SOAP message

EndpointReference in the addressing context		 0..1 The absolute URI that specifies the address of the intended receiver of the message. If this value is not specified, it defaults to the anonymous URI that is defined in the specification: http://www.w3.org/2005/08/addressing/anonymous.

In the addressing context, the <wsa:To> MAP is represented as an EPR. When the <wsa:To> is sent as part of a SOAP message it is split into its address and its reference parameters, as defined by the schema.
[reference parameters] * [reference parameters]* xs:any 0..unbounded Parameters that correspond to <wsa:ReferenceParameters> properties of the endpoint reference to which the message is addressed. This value is optional.
[source endpoint] <wsa:From> EndpointReference 0..1 A reference to the endpoint from which the message originated. This value is optional.
[reply endpoint] <wsa:ReplyTo> EndpointReference 0..1 An endpoint reference for the intended receiver of replies to this message. This value is optional.

If this value is not specified, it defaults to http://www.w3.org/2005/08/addressing/anonymous.
[fault endpoint] <wsa:FaultTo> EndpointReference 0..1 An endpoint reference for the intended receiver of faults relating to this message. This value is optional and defaults to the value of the <wsa:ReplyTo> MAP.
[relationship] * <wsa:RelatesTo> xs:anyURI plus optional attribute of type xs:anyURI 0..unbounded A pair of values that indicate how this message relates to another message. The contents of this element conveys the <wsa:MessageID> of the related message. An optional attribute conveys the relationship type. This value is optional.

If this value is not specified, it defaults to http://www.w3.org/2005/08/addressing/reply.
[message id] <wsa:MessageID> xs:anyURI   An absolute URI that uniquely identifies the message. This value is optional; if not supplied, CICS generates a value for outbound requests and responses.
The following example of a SOAP message contains WS-Addressing MAPs:
<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope"
            xmlns:wsa="http://w3.org/2005/08/addressing"
            xmlns:example="http://example.ibm.com/namespace">
  <S:Header>
      ...
      <wsa:To>http://example.ibm.com/enquiry</wsa:To>
      <wsa:ReplyTo>
        <wsa:Address>http://example.ibm.com/enquiryReply</wsa:Address>
      </wsa:ReplyTo>
      <wsa:Action>...</wsa:Action>
      <example:AccountCode wsa:IsReferenceParameter='true'>123456789</example:AccountCode>
      <example:DiscountId wsa:IsReferenceParameter='true'>ABCDEFG</example:DiscountId>
      ...
  </S:Header>
  <S:Body>
  ...
  </S:Body>
</S:Envelope>

Endpoint references

An endpoint reference is a specific type of MAP, which provides a standard mechanism to encapsulate information about specific endpoints. Endpoint references can be sent to other parties and used to target the web service endpoint that they represent. The following table summarizes the information model for endpoint references.
Table 2. Information model for endpoint references
Abstract property name Property type Multiplicity Description
[address] xs:anyURI 1..1 The absolute URI that specifies the address of the endpoint.
[reference parameters] * xs:any 0..unbounded Namespace qualified element information items that are required to interface with the endpoint.
[metadata] xs:any 0..unbounded Description of the behavior, policies, and capabilities of the endpoint.
The following XML fragment illustrates an endpoint reference. The <wsa:EndpointReference> element references the endpoint at the URI http://example.ibm.com/enquiry and contains metadata specifying the interface to which the endpoint reference refers and some application-specific reference parameters.
<wsa:EndpointReference
    xmlns:wsa="http://www.w3.org/2005/08/addressing"
    xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"
    xmlns:example="http://example.ibm.com/namespace">
  <wsa:Address>http://example.ibm.com/enquiry</wsa:Address>
  <wsa:Metadata
      xmlns:wsdli="http://www.w3.org/ns/wsdl-instance"
      wsdli:wsdlLocation="http://example.ibm.com/wsdl/wsdl-location.wsdl">
    <wsam:InterfaceName>example:reservationInterface</wsam:InterfaceName>
  </wsa:Metadata>
  <wsa:ReferenceParameters>
      <example:AccountCode>123456789</example:AccountCode>
      <example:DiscountId>ABCDEFG</example:DiscountId>
   <wsa:ReferenceParameters>
</wsa:EndpointReference>

WS-Addressing MAPs of type wsa:EndpointReferenceType are: <wsa:From>, <wsa:ReplyTo>, and <wsa:FaultTo>. However, the <wsa:To> MAP is defined in the WS-Addressing 1.0 standard as having a type of xs:anyURI. For simplicity CICS treats <wsa:To> MAPs in the addressing context as EPRs. When a <wsa:To> MAP is sent as part of a SOAP message, CICS splits it into its address and reference parameters, as required by the standard. For an example of how CICS handles the <wsa:To> element, see Web Services Addressing example.

Default namespaces

The following prefix and corresponding namespaces are referred to throughout the WS-Addressing documentation:
Table 3. Prefix and corresponding namespace
Default prefix Namespace
xs http://www.w3.org/2001/XMLSchema
wsa http://www.w3.org/2005/08/addressing (Recommendation schema)
http://schemas.xmlsoap.org/ws/2004/08/addressing (Submission schema)
wsam http://www.w3.org/2007/05/addressing/metadata