WS-Routing Specification Index Page

  • Article

 

WS-Routing is a simple, stateless, SOAP-based protocol for routing SOAP messages in an asynchronous manner over a variety of transports like TCP, UDP, and HTTP. With WS-Routing, the entire message path for a SOAP message (as well as its return path) can be described directly within the SOAP envelope. It supports one-way messaging, two-way messaging such as request/response and peer-to-peer conversations, and long running dialogs.

Specification

WS-Routing

Schema

SOAP-rp path construct

Status

WS-Routing was first published as SOAP-RP on 23 May 2001. This version of WS-Routing was published on 16 October 2001.

AppNote

Introduction

The Web Services Routing Protocol (WS-Routing) defines mechanisms for routing SOAP messages. SOAP is a lightweight wire protocol that defines a serialization mechanism to transport method calls to be used in application layer protocols. SOAP does not actually define a mechanism for sending a message from one party to another, even though it refers to a virtual message path. WS-Routing (formerly known as SOAP-RP) is a stateless protocol that extends SOAP by defining a means to specify an ordered route, or path, from the originator of the message, through intermediaries, to the ultimate message receiver.

Composable Architecture

By using the SOAP extensibility model, SOAP-based specifications are designed to be composed with each other to provide a rich messaging environment. WS-Routing does not define the means for reliable or secure messaging; other SOAP extensions are expected to provide these capabilities. It also does not attempt to define new transports.

Goals and Non-Goals

Taking a minimalist approach, WS-Routing encapsulates a message path within a SOAP message, so that the message contains enough information to be sent across the Internet using transports like TCP and UDP while supporting:

  • The SOAP message path model,
  • Full-duplex, one-way message patterns,
  • Full-duplex, request-response message patterns, and
  • Message correlation.

WS-Routing does not define the means for reliable or secure messaging; other SOAP extensions are expected to provide these capabilities. It also does not attempt to define new transports.

Details

WS-Routing defines a new SOAP header and associated processing model. To illustrate this, consider a SOAP processor A that wishes to send a SOAP message to an ultimate receiver D via B and then via C, as shown in Figure 1.

Figure 1. SOAP Processor A sending a SOAP message to D via B and then C

To express such routes, WS-Routing defines a new SOAP header named "path", and, within that header,

  • a "from" element for the message originator (A),
  • a "to" element for the ultimate receiver (D),
  • a "fwd" element to contain the forward message path, and
  • a "rev" element to contain the reverse message path.

The rev element is defined by WS-Routing to enable two-way messaging exchange. Both fwd and rev contain "via" elements to describe each intermediary (B and C). Other elements are defined for message identification, correlation, and intent.

The listing below illustrates how the path in the diagram above may be represented within the message by SOAP processor A. Note that there is no requirement that A knows the complete path in advance; the path may be discovered dynamically. (See the WS-Referral Specification Index.)

<SOAP-ENV:Envelope
      xmlns:SOAP-ENV="https://www.w3.org/2001/06/soap-envelope">
   <SOAP-ENV:Header>
      <wsrp:path xmlns:wsrp="https://schemas.xmlsoap.org/rp/">
         <wsrp:action>https://www.im.org/chat</wsrp:action>
         <wsrp:to>soap://D.com/some/endpoint</wsrp:to>
         <wsrp:fwd>
            <wsrp:via>soap://B.com</wsrp:via>
            <wsrp:via>soap://C.com</wsrp:via>
         </wsrp:fwd>
         <wsrp:from>soap://A.com/some/endpoint</wsrp:from>
         <wsrp:id>uuid:84b9f5d0-33fb-4a81-b02b-5b760641c1d6</wsrp:id>
      </wsrp:path>
   </SOAP-ENV:Header>
   <SOAP-ENV:Body>
      ...
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

As a message moves along a path, each hop along the way moves its corresponding via element from the fwd path to the rev path, dynamically constructing a path back to the sender. Other processing details cover gateways and routing-specific SOAP faults.

Implications

Because WS-Routing information is carried entirely within a SOAP header, the SOAP message is self-contained and self-describing, and is therefore relatively transport independent. The transports used to communicate between intermediaries are not defined by WS-Routing; the transport envelope is whatever the transport provides directly (e.g., a TCP packet for TCP). WS-Routing defines bindings to DIME, TCP, UDP, and HTTP, but one could use SSL/TLS, SOCKS, or others just as well.

WS-Routing supports both one-way and request-reply message exchange paradigms. When used with a bi-directional transport (e.g., TCP), it is possible to send one-way and request-reply messages in either direction, independent of which SOAP processor initiated the original transport-level connection.

WS-Routing is a building block that may be used together with other SOAP-based protocols to provide a complete set of services required by secure and reliable messaging environments. Specifically, the path header defined by WS-Routing may be safely composed with the headers defined by WS-Security; the latter headers may reference the former to ensure integrity and/or confidentiality. Similarly, WS-Routing does not define any reliability or retransmission policies; it is expected that these will be specified by another, SOAP-based reliability protocol.