Web Services Addressing (WS-Addressing)
August 2004
Authors
DON Box, Microsoft (Editor)
Erik Christensen, Microsoft
Francisco Curbera, IBM (Editor)
Donald Ferguson, IBM
JEFFREY FREY, IBM
Marc Hadley, Sun Microsystems, Inc.
Chris Kaler, Microsoft
David Langworthy, Microsoft
Frank LEYMANN, IBM
Brad love, Microsoft
Steve Lucco, Microsoft
Steve millet, Microsoft
Nirmal Mukhi, IBM
Mark NOTTINGHAM, BEA
David Orchard, BEA
John Shewchuk, Microsoft
Eugène Sindambiwe, SAP
Tony Storey, IBM
Sanjiva Weerawarana, IBM
Steve Winkler, SAP
Copyright Notice
(c) 2002-2004 BEA SYSTEMS Inc., International Business Machines Corporation, Microsoft Corporation, Inc, SAP AG, AND SUN Microsystems. All Rights Reserve.
Permission to copy and display the WS-Addressing Specification (the "Specification"), in any medium without fee or royalty is hereby granted, provided that you include the following on ALL copies of the Specification that you make:
1. a link or url to the specification at this location.
2. The Copyright Notice As Shown in The Specification.
BEA Systems, IBM, Microsoft, SAP, and Sun (collectively, the "Authors") each agree to grant you a license, under royalty-free and otherwise reasonable, non-discriminatory terms and conditions, to their respective essential patent claims that they Deem Necessary TO Implement The WS-Addressing Specification.
THE SPECIFICATION IS PROVIDED "AS IS," AND THE AUTHORS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT iNFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.THE AUTHORS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OR Relating To Any Use or Distribution of The Specifications.
The name and trademarks of the Authors may NOT be used in any manner, including advertising or publicity pertaining to the Specifications or their contents without specific, written prior permission. Title to copyright in the Specifications will at all times remain with the Authors.
No Other Rights Are Grand by implication, Estoppel or Otherwise.
Abstract
WS-Addressing provides transport-neutral mechanisms to address Web services and messages. Specifically, this specification defines XML [XML 1.0, XML Namespaces] elements to identify Web service endpoints and to secure end-to-end endpoint identification in messages. This specification enables ...........................
STATUS
WS-Addressing and related specifications are provided as-is and for review and evaluation only. BEA, IBM, Microsoft, SAP, and Sun make no warrantees or representations regarding the specifications in any manner whatsoever.
Table of contents
INTRODUCTION
1.1 Notational Conventions1.2 Namespaces
2. Endpoint References
2.1 Information Model for Endpoint References
2.2 Endpoint Reference XML Infoset Reperestation
2.3 Binding Endpoint References
2.4 Endpoint Reference Compaison
3. Message Information HEADERS
3.1 Message Information Headers XML Infoset Reperestation
3.2 Formulating a reply message
3.3 Associating Action with WSDL Operations
3.3.1 Explicit Association
3.3.2 Default Action Pattern
4. Faults
4.1 Invalid Message Information HEADER
4.2 Message Information Header Required
4.3 Destination Unreachable
4.4 Action Not Supported
4.5 Endpoint Unavailable
5. Security Considances
6. ACKNOWLEDGEMENTS
7. References
INTRODUCTION
Web Services Addressing (WS-Addressing) defines two interoperable constructs that convey information that is typically provided by transport protocols and messaging systems. 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 (referenceable) 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 convey 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 Following Example Illustrates The Use of these Mechanisms in A Soap: //business456.example/client1 to http: //fabrikam123.example/purchasing:
(001) XMLns: wsa = "http://schemas.xmlsoap.org/ws/2004/08/addressing"> (002) (003) (004) UUID: 6B29FC40-CA47-1067-B31D-00DD010662DA (005) (006) (007) (008) (009) (010) (012) (013) ... (014) (015) Lines (002) to (011) Repesent The Header of the Soap Message WHERE The Mechanisms Defined in The Specification Are Used. The Body Is RepreSented by Lines (012) TO (014). Lines (003) to (010) contain the message information header blocks. Specifically, lines (003) to (005) specify the identifier for this message and lines (006) to (008) specify the endpoint to which replies to this message should BE SENT AS An Endpoint Reference. Line (009) Specifies The Address Uri of The Ultimate Receiver of this Message. Line (010) Specifies An Action Uri Identifying Expected Semantics. 1.1 NOTATIONAL Conventions THE Keywords "Must", "Must Not", "Required", "SHALL", "SHALL NOT", "Shove", "Recommended", "May", and "Optional" in this document area to TO Be Interpreted As Described in RFC 2119 [RFC 2119]. When describing abstract data models, this specification uses the notational convention used by the XML Infoset [XML Infoset]. Specifically, abstract property names always appear in square brackets (e.g., [some property]). When describing concrete XML schemas [XML Schema Part 1, Part 2], this specification uses the notational convention of WS-Security [WS-Security]. Specifically, each member of an element's [children] or [attributes] property is described using an Xpath-Like Notation (EG, / X: myHeader / x: SomeProperty / @ value1). The use of {any} indeicates the presence of an element wildcard ( THIS SPECification Uses a Number of Namespace Prefixes Throughout; The a list in Table 1. NOTE That The Choice of Any Namespace Prefix is Arbitrary and Not Semantical Significant (See [XML Namespaces]). PrefixNamespaceShtp: //www.w3.org/2003/05/soap-ENvelop: //schemas.xmlsoap.org/ws/2004/08/addressing wsphttp: / /SChemas.xmlsoap.org/ws/2002/12/policy xshttp://www.w3.org/2001/xmlschema Table 1 prefixes and namespaces Used in this specific WS-Addressing is defined in terms of the XML Information Set [XML Infoset] WS-Addressing is conformant to the SOAP 1.2 [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 [WSDL 1.1] Described Services. The Examples In this specification use an xml 1.0 [xml 1.0] Reperesentation But this is not a required. All information items defined by WS-Addressing are identified by the XML namespace URI [XML Namespaces] "http://schemas.xmlsoap.org/ws/2004/08/addressing". A normative XML Schema [XML Schema Part 1, Part 2] Document Can Be Obtained by Dereferencing The XML Namespace Uri. 2. Endpoint ReferenceSthis Section Defines The model and syntax of an endpoint reference. 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 [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 interact. 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 can not be used to cover the use cases listed .. above Endpoint references logically extend the WSDL description model (eg, portTypes, bindings, etc.), but do not replace it Endpoint references will be used instead of WSDL 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 complement and do not replace the WSDL / 1.1 2.1 Information Model for Endpoint References An Endpoint Reference Consists of the Following Abstract Properties: [Address]: URI (Mandatory) . [Reference Properties]: XS: ANY (0..Unbounded). A reference may contain a number of individual properties that are required to identify the entity or resource being conveyed. Reference identification properties are element information items that are named by QName and are required to properly dispatch messages to endpoints at the endpoint side of the interaction. Reference properties are provided by the issuer of the endpoint reference and are otherwise assumed to be opaque to consuming applications. The interpretation of these properties (as the use of the endpoint reference in general) is dependent upon the protocol binding and data encoding used to interact with the endpoint. Section 2.3 below defines the default binding for the SOAP protocol. Consuming applications SHOULD assume that endpoints represented by endpoint references with different [reference properties] may accept different sets of messages or follow a different set of policies, and consequently may have Different Associated Metadata (WSDL, XML Schema, and WS-Policy Policies). The Relationship Between Reference Properties and endpoint policies is further explained in section 2.4. [Reference Parameters]: XS: ANY (0..Unbounded). A reference may contain a number of individual parameters which are associated with the endpoint to facilitate a particular interaction. Reference parameters are element information items that are named by QName and are required to properly interact with the endpoint. Reference parameters are also provided by the issuer of the endpoint reference and are otherwise assumed to be opaque to consuming applications. The use of reference parameters is dependent upon the protocol binding and data encoding used to interact with the endpoint. Section 2.3 describes the default binding for the SOAP protocol. Unlike [reference Properties], The [Reference Parameters] of Two Endpoint References May Difer WInout An Implication That Different XML Schema, WSDL or Policies Apply to the endpoints. [SELECTED Port Type]: Qname (0..1) The Qname of The Primary PortType of the endpoint being conveyed. [service-port]: (QNAME, NCNAME (0..1)) (0..1) This is the QName identifying the WSDL service element that contains the definition of the endpoint being conveyed. The service name provides a link to a full description of the service endpoint. An optional non-qualified name identifies the specific port in the service that corresponds to The endpoint. [Policy]: WSP: Policy (0..Unbounded) A Variable Number of XML Policy Elements As Described in WS-Policy [ 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. However, embedded policies are not authoritative and may be stale OR incoherent with the policies associated with the endpoint at the time when the interaction Occurs.2.2 Endpoint Reference XML Infoset Reperestation THIS Section Defines An XML Infoset-based REPRESENTATION for An Endpoint Reference As Both An XML Type (WSA: EndpointReference "and as an xml element ( The WSA: EndpointReferenceErgeType Type IS Used WhereEver A Web Service Endpoint Is Reference. The Following Describes The Contents of this Type: The Following Describes The Attributes and Elements Listed in The Schema Overview Above: / WSA: EndpointReference This Repesents Some Element of Type WSA: EndPointReference. This Example Uses the predefined / WSA: EndpointReference / WSA: Address This Required Element (of type Xs: Anyuri) Specifies The "Property of The Endpoint Reference. This Address May Beh Service Endpoint./wsa: NendPointReference/wsa: ReerenceProperties/wsa: This Optional Element Contains The Elements That Convey The [Reference Properties] of The Reference. / WSA: EndpointReference / WSA: ReferenceProperties / {Any} Each Child Element of ReferenceProperties Repens An Individual [Reference Property]. / WSA: EndpointReference / WSA: ReferenceParameters / This Optional Element Contains The Elements That Convey The [Reference Parameters] of the reference. / WSA: EndPointReference / WSA: ReferenceParameters / {Any} Each Child Element of ReferenceParameters represents an Individual [Reference Parameter]. / WSA: EndPointReference / WSA: Porttype This Optional ELEMENT (Of Type XS: QNAME) Specifier The value of the [selected port type] Property of the endpoint reference. / WSA: EndpointReference / WSA: ServicesName This Optional ELEMENT (Of Type XS: QNAME) Specifies the / WSA: EndpointReference / WSA: ServiceName / @ portname This Optional Attribute (of type XS: ncname) Specifies the name of the / WSA: EndpointReference / WSP: Policy This Optional Element Specifies a Policy That Relevant To The Intertion with the endpoint. / wsa: endpointReference / {any} This is an extensibility mechanism to allow additional elements to be specified. / wsa: endpointReference / @ {any} This is an extensional attributes to baspecified. The following illustrates an endpoint reference This element references the port of type. "Fabrikam: InventoryPortType" at the URI "http: //www.fabrikam123.example/acct" 2.3 Binding Endpoint References When a message needs to be addressed to the endpoint, the information contained in the endpoint reference is mapped to the message according to a transformation that is dependent on the protocol and data representation used to send the message. Protocol-specific mappings (or bindings) will define how the information in the endpoint reference is copied to message and protocol fields This specification defines the SOAP binding for endpoint references This mapping MAY be explicitly replaced by other bindings (defined as WSDL bindings or as policies);.. however, in the absence of an applicable policy stating that a different mapping must be used, the SOAP binding defined here is assumed to apply. to ensure interoperability with a broad range of devices, all conformant implementations MUST support the SOAP binding. The soap binding for endpoint references is defined by The Following TWU Rules: The [address] property in the endpoint reference is copied in the [destination] header field of the SOAP message. Each [reference property] and [reference parameter] element becomes a header block in the SOAP message. The element information item of each [ reference property] or [reference parameter] (including all of its [children], [attributes] and [in-scope namespaces]) is to be added as a header block in the new message.The next example shows how the default SOAP binding For Endpoint References IS Used to Construct A Message Addressed to the Endpoint: According to the mapping rules stated before, the address value is copied in the "To" header and the "CustomerKey" element should be copied literally as a header in a SOAP message addressed to this endpoint The SOAP message would look as follows.: XMLns: WSA = "..." XMLns: Fabrikam = "..."> ... ... ... 2.4 Endpoint Reference Compaison During the course of Web services interactions applications may receive multiple endpoint references describing the endpoints it needs to interact with. Different copies of an endpoint reference may also be received over time. The Following Rules Clarify The Relation Between The Behaviors of the Endpoints Represented by Two Endpoint References with the Same [Address] and the same [reason "]. The two endpoints accept the same sets of messages, and follow and require the same set of policies. That is, the XML Schema, WSDL, and WS-Policy metadata applicable to the two references are the same. In particular, the policies applicable to The Two Endpoints Are The Same Regardless Of The VALUES OF THE Embedded [Policy]. Embedded Policies Are Not Authoritative and May Be Stale Or IncOherent with the policies associated with the endpoint. THE [ADRESS] OF TOETINT REFERENCES ARE Compared According to Section 6 of [RFC 2396] of Two Endpoint References Are Equal IF: they contain the same number of individual properties; for each reference property in one endpoint reference there exists an equivalent reference property in the other One [reference property] is equivalent to another [reference property] if their byte streams per Exclusive XML Canonicalization are equal. . The WSDL Definitions and Policies Apply To Endpoint References WHOSDRESS or Reference Properties Diffe. 3. Message Information HEADERS This Section Defines The Model and Syntax of a Message Information Header. The message information headers collectively augment a message with the following abstract properties. These properties enable the identification and location of the endpoints involved in an interaction. The basic interaction pattern from which all others are composed is "one way". In this pattern a source sends a message to a destination without any further definition of the interaction. "Request Reply" is a common interaction pattern that consists of an initial message sent by a source endpoint (the request) and a subsequent message sent from the destination of the request back To the source (the reply). a reply can be each estival, or any other. The Properties Below Support One Way, Request Reply, And Any Other Intertion Pattern: [Destination]: URI (Mandatory) The address of the intended receiver of this message. [Source endpoint]: endpoint reference (0..1) Reference of the endpoint where the message originated from. [reply endpoint]: endpoint reason (0..1) An endpoint reference that identifies the intended receiver for replies to this message. If a reply is expected, a message MUST contain a [reply endpoint]. The sender MUST use the contents of the [reply endpoint] to formulate the reply message as defined in Section 3.2. If the [reply endpoint] is absent, the contents of the [source endpoint] may be used to formulate a message to the source. This property MAY be absent if the message has no meaningful reply. If this property is present, The [Message ID] Property is Required. [Fault Endpoint]: Endpoint Reference (0..1) An endpoint reference that identifies the intended receiver for faults related to this message. When formulating a fault message as defined in Section 3.2 and 4, the sender MUST use the contents of the [fault endpoint] of the message being replied to to formulate the fault message. If the [fault endpoint] is absent, the sender MAY use the contents of the [reply endpoint] to formulate the fault message. If both the [fault endpoint] and [reply endpoint] are absent, the sender MAY use the contents of the [source endpoint] to formulate the fault message. This property may be absent if the sender can not receive fault messages (eg, is a one-way application message). If this property is present, the [message id] property is REQUIRED [action]: URI (Mandatory) An Identifier That Unique (and opaquel) Identifies The Semantics Implied by this message. It is RECOMMENDED that value of the [action] property is a URI identifying an input, output, or fault message within a WSDL port type. An action may be explicitly or implicitly associated with the corresponding WSDL definition. Section 3.3 below describes the mechanisms of . [Message ID]: URI (0..1) A URI that uniquely identifies this message in time and space. No two messages with a distinct application intent may share a [message id] property. A message MAY be retransmitted for any purpose including communications failure and MAY use the same [message id] property . The value of this property is an opaque URI whose interpretation beyond equivalence is not defined in this specification If a reply is expected, this property MUST be present [relationship]:.. (QName, URI) (0..unbounded) A pair of values that indicate how this message relates to another message. The type of the relationship is identified by a QName. The related message is identified by a URI that corresponds to the related message's [message id] property. The message identifier URI may REFER TO A Specific Message, or Be The Following Well-KNown Uri That Means "Unspecified Message:" http://schemas.xmlsoap.org/ws/2004/08/addressing/id/unspecified This Specification HAS One Predefined Relationship Type: Qname Description WSA: Reply INDICES THAT this is a reply to the message identified by the URI. A Reply Message Must Contain A [RELATIONSHIP] Property Consisting Of WSA: Reply and the message ID Property of The Request Message. . ,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, Due to the range of network technologies currently in wide-spread use (eg, NAT, DHCP, firewalls), many deployments can not assign a meaningful global URI to a given endpoint. To allow these "anonymous" endpoints to initiate message exchange patterns and receive REPLIES, WS-Addressing Defines The Following Well-KNown Uri for Use by Endpoints That Cannot Have A Stable, Resolvable Uri.http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous Requests whose [reply endpoint], [source endpoint] and / or [fault endpoint] use this address MUST provide some out-of-band mechanism for delivering replies or faults (eg returning the reply on the same transport connection). This mechanism may BE A Simple Request / Reply Transport Protocol (EG, HTTP GET or POST). THIS URI May Be Used As The [Destination] for reply message and sales not be used as the [destination] in Other Circumstances. 3.1 Message Information Headers XML Infoset Reperestation The message information header blocks provide end-to-end characteristics of a message that can be easily secured as a unit. The information in these headers is immutable and not intended to be modified along the message path. The Following Describes The Contents of The Message Information Header Blocks: The Following Describes The Attributes and Elements Listed in The Schema Overview Above: / WSA: MessageId This Optional ELEMENT (Of Type XS: Anyuri) Conveys The [Message ID] Property. This Element Must Be Present IF WSA: Replyto or WSA: Faultto Is Present. / WSA: Requeatesto THIS OPTIONAL (REPEATING) Element Information Item Contributes One Abstract [Relationship] Property Value, In The Form of A (URI, QNAME) Pair. The [Children] Property of this Element (Which is of Type Xs: Anyuri) CONVEYS The [Message ID] of The Related Message. This Element Must Be Present IF The message is a reply. / WSA: Requeesto / @ RelationshipType This Optional Attribute (of type XS: Qname) Conveys The Relationship Type as a Qname. When Absent, The Implied Value of this Attribute IS WSA: Reply. / WSA: Replyto This Optional ELEMENT (Of Type WSA: EndPointReference, pROVIDES The value for the [reply endpoint] Property. This Element Must be present if a reply is expected. IF this element is present, WSA: MessageId Must Be Present. / WSA: from This Optional ELEMENT (Of Type WSA: EndPointReferenceErgeType) Province The value for the [source endpoint]. / WSA: Faultto This Optional ELEMENT (Of Type WSA: EndPointReferenceEnceType) Provides the value for the [fault endpoint] Property. IF this element is present, WSA: MessageId Must Be Present. / WSA: To This Required Element (of type Xs: anyuri) provides the value for the [destination] property. / WSA: Action This Required Element of Type ............................ ...CRIPLILE, APPLICATIONS. 3.2 Formulating a reply message The reply to a WS-Addressing compliant request message MUST be compliant to WS-Addressing and be constructed according to the rules defined in this section.The following example illustrates a request message using message information header blocks in a SOAP 1.2 message: XMLns: wsa = "http://schemas.xmlsoap.org/ws/2004/08/addressing" XMLns: f123 = "http://www.fabrikam123.example/svc53"> This Message Would Have The Following Property Values: [destination] The Uri Mailto: Joe@fabrikam123.example [reply endpoint] The endpoint with [address] http://business456.example/client1 [Action] http://fabrikam123.example/mail/delete [Message ID] UUID: AAAABBBB-CCCC-DDDD-EEEE-FFFFFFFFFFFF The Following Example Illustrates a reply message Using Message Information Header Blocks in A SOAP 1.2 Message: XMLns: wsa = "http://schemas.xmlsoap.org/ws/2004/08/addressing" XMLns: f123 = "http://www.fabrikam123.example/svc53"> UUID: AAAABBBB-CCCC-DDDD-Eeee-wwwwwwwwwww UUID: Aaaabbb-cccc-dddd-eeee-ffffffffffffff http://business456.example/client1 This Message Would Have The Following Property Values: [destination] http://business456.example/client1 [action] http://fabrikam123.example/mail/deleteack [Message ID] UUID: AAAABBBB-CCCC-DDDD-EEEE-Wwwwwwwwww [RELATIONSHIP] (WSA: Reply, UUID: Aaaabbb-cccc-dddd-eeee-ffffffffffff) 3.3 Associating Action with WSDL Operations . 3.3.1 Explicit Association ......................... .. For Example Consider The Following WSDL Excerpt: ...
WSA: Action = "http://example.com/getquote" />
