Share via

WS-Referral Specification Index Page

  • Article

 

Brief

WS-Referral is a protocol that enables the routing strategies used by SOAP nodes in a message path to be dynamically configured. SOAP itself provides a distributed processing model where SOAP messages can have content destined for specific processing nodes. WS-Routing adds to SOAP the capability of describing the actual message path. WS-Referral provides a mechanism to dynamically configure SOAP nodes in a message path to define how they should handle a SOAP message. It is a configuration protocol that enables SOAP nodes to delegate part or all of their processing responsibility to other SOAP nodes.

Specification

WS-Referral

Schema

WS-Referral

Status

WS-Referral was published as a public specification on 16 October 2001.

ApNotes

Introduction

Web Services Referral Protocol (WS-Referral) is a simple SOAP-based protocol for configuring instructions about message paths (routing entries) in SOAP nodes that relay SOAP messages (SOAP routers). WS-Referral is orthogonal to the Web Services Routing Protocol (WS-Routing) in that WS-Referral provides a way to configure how SOAP routers will build a message path, whereas WS-Routing provides a mechanism for describing an actual path of a message.

WS-Referral aids in the configuration of message paths, which in turn enables a variety of services. In addition to relay services such as high performance overlay message delivery or corporate firewall services, SOAP routers can provide Web services like load-balancing, mirroring, caching, and client authentication services. As an example, a Web service may delegate responsibility for some aspects of its service to third parties in a manner that is transparent to users of that service.

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. As such, WS-Referral does not itself provide for services such as message security, path description, or service discovery. These features are provided by other Web service specifications.

Goals and Non-Goals

WS-Referral is designed to be used both for administrative configuration of quasi-static routes, and for dynamic route construction. Routes can be amended after their initial configuration, including forwarding the message to delegated parties. Since WS-Referral uses SOAP messages and headers to exchange routing entries, it can change routes on timescales independent of the propagation time of the underlying protocol's routing tables.

WS-Referral is extensible in that all of its key components can be enhanced with additional elements. For example, new elements can extend the logic of when a given routing entry should be applied to a message.

Referral Statements

The basic unit in WS-Referral is the referral statement. The referral statement has five elements:

  1. for: Indicates the URIs (also called SOAP actors) for which the referral is intended.
  2. if: A set of conditions that the recipient of the referral must understand in order to use the referral.
  3. go: If a SOAP message is headed for a SOAP actor (for which this referral is intended) and the set of conditions are fulfilled, then send the message via one of the SOAP routers listed in the go element.
  4. desc: Additional information that the recipient need not understand in order to use the referral, but may find useful.
  5. refId: A unique identifier for a referral so that it is possible to identify a specific representation of a referral.

While occasionally grouped for convenience, each referral statement can be evaluated independently of any other referral.

Separating elements into "if" and "desc" elements enables detailed control of the behavior of SOAP routers that do not understand a new element. An application extending WS-Referral with a new "if" condition, e.g., "only use this referral if the message is from bob@corp.com," is guaranteed that the recipient will not use the referral unless it understands the condition.

Only two mandatory "if" conditions are defined by WS-Referral. The first is "invalidates", which can be used to cancel previously exchanged referrals. The second is "ttl", which sets a time to live limit on the validity of a referral.

The "Desc" element can be used to carry information that optionally may be used by the recipient. For example, WS-Referral has no inherent rule for differentiating between multiple SOAP routers listed in the "go" element. An application wanting to give a hint of which to chose, like "select the one that is closest to the sender," could add a condition to the "desc" section, since the logic of the application would not be affected if the receiver used the referral without understanding the condition.

Messages

Referral statements are exchanged via three mechanisms:

  1. Register messages: This SOAP message instructs the receiver to utilize the enclosed referral statement. The recipient explicitly accepts or rejects the registration.
  2. Query messages: A SOAP router can be queried for referrals with this SOAP message. This message may be extended to allow complex queries.
  3. Referrals header: Any SOAP message can be augmented with a "referrals" SOAP header containing referral statements. This allows a mechanism to piggyback referrals on existing message exchange streams.

Register and query messages are typically used by an administrator to configure a set of SOAP routers on a path. Register provides a "push" method of updating the SOAP level routing tables in a router. Query provides a "pull" method, which a router may use to learn about message paths.

The "referrals" SOAP header is typically used in dynamic environments, where updates to message paths are cached. As part of an existing message exchange, a SOAP router would include a "referrals" SOAP header to indicate to a sender a better path to reach a desired SOAP actor.

Example

The interaction between WS-Referral and WS-Routing provides a straightforward example of how WS-Referral can be used. The following referral would cause the sender of a WS-Routing message bound for soap://b.org service to add an additional forward path "via" element to soap://c.org.

<r:ref xmlns:r="https://schemas.xmlsoap.org/ws/2001/10/referral">
 <r:for>
  <r:prefix>soap://b.org</r:prefix>
 </r:for>
 <r:if/>
 <r:go>
  <r:via>soap://c.org</r:via>
 </r:go>
 <r:refId>mid:1234@some.host.org</r:refId>
</r:ref>

The prefix tag above means that any URI beginning with the contained URI is considered a match for the referral. How the recipient could use this referral on future messages is show below. Added elements are indicated in bold.

<S:Envelope xmlns:S="https://www.w3.org/2001/09/soap-envelope">
 <S:Header>
  <m:path xmlns:m="https://schemas.xmlsoap.org/rp/">
   <m:action>https://www.notification.org/update</m:action>
   <m:to>soap://b.org/service/</m:to>
   <m:fwd>
    <m:via>soap://c.org</m:via>
   </m:fwd>
   <m:from>soap://a.org</m:from>
   <m:id>mid:1001@a.org</m:id>
  </m:path>
 </S:Header>
 <S:Body>
  ...
 </S:Body>
</S:Envelope>