Qworum specification, version 0.9

Introduction
Composing services with Qworum

Multi-phase service calls
Special case: the World Wide Web
Special case: RPC
The user agent as mediator for service calls

Messages

Composition messages
Result messages
The application/x-qworum+xml media type
The .qrm file extension

Message elements

The http://www.qworum.com/ XML namespace
The call element
The fault element
The goto element
The nil element
The title element

Appendices

Handling non-conforming messages
References
Revision history

1. Introduction

The World Wide Web is a system of interlinked hypertext documents accessed via the Internet. Although its initial purpose was to provide an infrastructure for information, the World Wide Web is increasingly being used for web applications, which arguably have additional infrastructure needs. Qworum complements existing web standards by addressing the composition needs of web applications.

With Qworum, the barriers that exist between websites are largely overcome, so that websites can provide services to each other much more easily. In particular, websites can provide interactive services that seamlessly integrate into other websites. To this end, Qworum defines a web message format that is used for service composition.

For service providers, the advantage of using Qworum is that services can be interactive as a regular website, or non-interactive as a remote procedure call. In fact, the same service may be interactive during one call, and non-interactive during the next one. In other words, Qworum unifies the World Wide Web and remote procedure call concepts.

The functionality offered by Qworum is orthogonal to that of existing web formats such as HTML. As a result, the Qworum specification is expected to evolve independently from those standards.

The present specification provides relevant information for the following groups:

Developers of Qworum-based services, and
Developers of user agents.

2. Composing services with Qworum

Qworum is based on the concept of multi-phase services. The service composition mechanism used by Qworum is directly derived from this concept, and explains the design choices made by Qworum. This and related concepts are described below.

The term phase refers to the following three consecutive steps:

a user agent sends a request to a server,
the server performs an operation based on the request and produces a response,
the user agent receives the response from the server.

A phase

According to this definition, conventional remote procedure calls (based on XML-RPC for instance) always consist of a single phase.

The term service refers to a software functionality available on a computer, and used by programs on other computers through network connections. In the context of Qworum, a service is available at a URL that has an http or https scheme, and services are identified by their URL.

2.1. Multi-phase service calls

The term multi-phase service refers to a service whose calls consist of one or more phases. A multi-phase service call may span several servers, and terminates when the user agent receives a response containing a result message.

In order to continue the current call, a phase may return a response that does not contain a result message. In this case, the user agent will try to use the message for initiating the next phase of the current call. When the HTTP protocol is used, HTTP redirections and interaction messages such as HTML pages allow such call continuations. Another way of performing call continuations is through the use of composition messages, as described below.

A multi-phase service call consisting of three phases, using the HTTP protocol

2.2. Special case: the World Wide Web

The multi-phase service call concept is more general than the World Wide Web paradigm.

Indeed, a web browsing session inside a browser tab (or window) is in fact equivalent to a multi-phase service call which never returns a result, and which never calls other services by using the Qworum composition mechanism.

2.3. Special case: RPC

The multi-phase service call concept is also more general than the concept of remote procedure call: a multi-phase service call consisting of a single phase is equivalent to a conventional remote procedure call.

2.4. The user agent as mediator for service calls

With Qworum, a service calls another service by sending a composition message to the user agent. Based on the instructions contained in this message, the user agent then performs the service call, between two consecutive phases of the calling service.

The service call terminates when one of its phases sends a result message to the user agent. The user agent then sends the received result to the calling service, at a URL specified in the composition message previously received.

Service composition with Qworum: a service on a first server calls a service on a second server

Qworum does not impose any limitation on the number of nested calls: a service may call another service, which calls another service, which calls yet another service, etc. A service may also make recursive calls to itself.

The user agent maintains an internal stack for handling the service calls. In the case of a web browser, each tab or window has a call stack associated with it. Call stacks initially contain one frame, which represents the main service call. Call frames are used for storing composition messages. The topmost call frame, corresponding to the currently executing service call, does not contain any composition message.

3. Messages

Qworum messages are XML documents. A message that is not a well-formed XML document does not conform to the present specification; user agents must handle such messages according to the rules of section 5.1.

User agents supporting this version of the Qworum specification must also support the HTTP [1] [2] and HTTPS [3] protocols, and recognize and handle Qworum messages contained in HTTP and HTTPS responses.

User agents must use the following rules for handling Qworum messages:

User agents supporting a version of the Qworum specification must also support all preceding versions of the specification.
User agents must first try to handle a Qworum message according to the latest Qworum version they support.

3.1. Composition messages

Services send composition messages to user agents in order to perform service calls. Composition messages convey the following information to the user agent:

The next phase of the service making the call, represented by the goto element,
The first phase of the called service, represented by the call element,
An optional call parameter which will be POSTed to the called service by using the application/xml media type.

Here is a composition message:

<qrm:goto href='checked_out' xmlns:qrm='http://www.qworum.com/'>
  <qrm:call href='https://www.apaymentprocessingsite.com/process_payment'>
    <payment>
      <description>1 x 1-year subscription for "A Business Magazine"</description>
      <total>98.95</total>
      <currency>USD</currency>
      <merchant>payments@anecommercesite.com</merchant>
    </payment>
  </qrm:call>
</qrm:goto>

A user agent receiving this message from http://www.anecommercesite.com/check_out will infer that:

The next phase of the service making the call has the URL http://www.anecommercesite.com/checked_out,
The first phase of the called service has the URL https://www.apaymentprocessingsite.com/process_payment,

The call has the following parameter:

<payment>
  <description>1 x 1-year subscription for "A Business Magazine"</description>
  <total>98.95</total>
  <currency>USD</currency>
  <merchant>payments@anecommercesite.com</merchant>
</payment>

The user agent executes this composition message as follows:

It first performs the service call.
If the call terminates by returning a fault, then the current call also terminates by returning that same fault, as does the previous call, and so on, until the main call terminates by returning that fault. The current version of the specification does not support fault catching.
If the call terminates normally, the corresponding call element is replaced by the root element of the result message that terminated the call.
The user agent then resumes the service which made the calls, as described by the goto element.

Composition messages may be used for redirections instead of service calls. The call element is absent in such messages.

A user agent receiving the following message from http://www.anecommercesite.com/check_out will initiate the next phase of the current call by issuing a GET request to http://www.anecommercesite.com/checked_out:

<goto href='checked_out' xmlns='http://www.qworum.com/' />

Redirections may also have parameters. A user agent receiving the following message from http://www.anecommercesite.com/check_out will initiate the next phase of the current call by issuing a POST request to http://www.anecommercesite.com/checked_out:

<qrm:goto href='checked_out' xmlns:qrm='http://www.qworum.com/'>
  <payment>
    <description>1 x 1-year subscription for "A Business Magazine"</description>
    <total>98.95</total>
    <currency>USD</currency>
    <merchant>payments@anecommercesite.com</merchant>
    <status>Processed</status>
    <transaction>185896449654</transaction>
  </payment>
</qrm:goto>

The POST request will have the following application/xml content:

<payment>
  <description>1 x 1-year subscription for "A Business Magazine"</description>
  <total>98.95</total>
  <currency>USD</currency>
  <merchant>payments@anecommercesite.com</merchant>
  <status>Processed</status>
  <transaction>185896449654</transaction>
</payment>

3.2. Result messages

Service calls terminate by sending a result message to the user agent.

If a call was completed successfully, then the result message is an XML document that satisfies one of the following conditions:

It does not use the Qworum vocabulary, or
It has nil as root element.

Here is a result message that contains meaningful data:

<payment>
  <description>1 x 1-year subscription for "A Business Magazine"</description>
  <total>98.95</total>
  <currency>USD</currency>
  <merchant>payments@anecommercesite.com</merchant>
  <status>Processed</status>
  <transaction>185896449654</transaction>
</payment>

Here is a result message returned by a call that has successfully completed, yet did not have meaningful data to issue:

<nil xmlns='http://www.qworum.com/' />

If a call could not execute successfully, then it should return a result message containing the fault element as root. Here is a result message returned by a service that did not receive an acceptable parameter:

<fault xmlns='http://www.qworum.com/'>
  <title>Wrong parameter<title>
</fault>

User agents may transform messages into result messages containing the fault element as root, under certain conditions.

3.3. The `application/x-qworum+xml` media type

The media type of Qworum messages is application/x-qworum+xml (media types are explained in the section 3.7 of the HTTP/1.1 specification [1]). This media type has an optional version parameter.

If a user agent supports Qworum, then the Accept headers of the HTTP requests it generates must include the Qworum media type. In this header, the user agent may also indicate the latest Qworum version it supports by using the version parameter. This parameter may be omitted if the user agent only supports Qworum version 0.9; it is mandatory otherwise.

Consequently, if a user agent only supports Qworum version 0.9, then the Accept headers of the HTTP requests it generates must include one of these two forms:

application/x-qworum+xml
application/x-qworum+xml;version=0.9

For example, a Qworum-enabled web browser might generate the following request header:

Accept: application/x-qworum+xml;version=0.9,text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5

If an HTTP response contains a Qworum message, then this media type must be used as the value of its Content-Type header. The version parameter should not be included in this header; the user agent will ignore it if present. For example, an HTTP response containing a Qworum message might include the following header:

Content-Type: application/x-qworum+xml

3.4. The `.qrm` file extension

The suggested extension for files containing a Qworum message is .qrm. For example, a file containing a composition message that calls a payment processing service might be named payment_processing_call.qrm.

4. Message elements

4.1. The `http://www.qworum.com/` XML namespace

Qworum defines an XML vocabulary that is used for service composition. All elements of this vocabulary belong to the namespace http://www.qworum.com/. Elements belonging to this namespace are also referred to as "Qworum elements". Elements that do not belong to this namespace are also referred to as "non-Qworum elements".

The Qworum elements call, fault, goto, nil and title are defined below.

4.2. The `call` element

A call element in a composition message indicates to the user agent that it has to initiate a service call on behalf of the service sending the message. Later, when the called service returns a result, that result will be used as parameter for the goto element which contains the call element.

call elements have an optional href attribute which indicates the URL of the first phase of the service to be called. The value of the href attribute may be an absolute HTTP or HTTPS URL [4], or a relative URL [5]. An absent href attribute is equivalent to an href attribute whose value is the URL of the composition message containing the call element. For example, a request to http://www.ahost.com/path may return any one of the following composition messages; they will all make the user agent initiate a recursive call to the current service by sending an HTTP GET request to http://www.ahost.com/path:

<goto href='http://www.anotherhost.com/' xmlns='http://www.qworum.com/'>
  <call />
</goto>

<goto href='http://www.anotherhost.com/' xmlns='http://www.qworum.com/'>
  <call href='path' />
</goto>

<goto href='http://www.anotherhost.com/' xmlns='http://www.qworum.com/'>
  <call href='http://www.ahost.com/path' />
</goto>

A call element may contain a parameter element. The parameter element does not belong to the Qworum namespace, and its descendant elements, if present, also do not belong to that namespace.

For example, an e-commerce site might send the user agent the following composition message for calling a secure payment processing service:

<qrm:goto href='checked_out' xmlns:qrm='http://www.qworum.com/'>
  <qrm:call href='https://www.apaymentprocessingsite.com/process_payment'>
    <!--
      The 'payment' parameter element and its descendants 
      do not belong to the Qworum namespace. 
    -->
    <payment>
      <description>1 x 1-year subscription for "A Business Magazine"</description>
      <total>98.95</total>
      <currency>USD</currency>
      <merchant>payments@anecommercesite.com</merchant>
    </payment>
  </qrm:call>
</qrm:goto>

4.3. The `fault` element

The fault element indicates that a service call has aborted with an error.

fault may be used as root element of result messages.

User agents transform some non-conforming Qworum messages into result messages containing a fault root element, according to the rules of section 5.1.

A fault element may contain a title element.

The following is a result message containing this element:

<fault xmlns='http://www.qworum.com/' />

4.4. The `goto` element

goto elements are used as root elements of composition messages, where they define the next phase of the current call. When a user agent receives a Qworum message containing this root element, it classifies the message as a composition message.

goto elements have an optional href attribute which indicates the URL of the next phase of the current call. The value of the href attribute may be an absolute HTTP or HTTPS URL [4], or a relative URL [5]. An absent href attribute is equivalent to an href attribute whose value is the URL of the message containing the goto element. For example, a request to http://www.ahost.com/path may return any one of the following composition messages; they will all make the user agent initiate the next phase of the current call by sending an HTTP GET request to http://www.ahost.com/path:

<goto xmlns='http://www.qworum.com/' />

<goto href='path' xmlns='http://www.qworum.com/' />

<goto href='http://www.ahost.com/path' xmlns='http://www.qworum.com/' />

A goto element may contain a parameter element, which consists of one of the following elements:

a call element, or
an element that does not belong to the Qworum namespace, and whose descendant elements, if present, also do not belong to that namespace.

If the parameter element is a call element, then the user agent performs this service call before handling the goto element.

If the parameter element is not a call element, or if there is no parameter element, then the composition message describes an operation similar to an HTTP redirection, rather than a service composition.

4.5. The `nil` element

The nil element indicates that a service call has terminated without error, but that it did not have any meaningful result to return. This element exists as a convenience for services; they may also use a non-Qworum element for this purpose.

nil may be used as root element of result messages.

This element does not have any attributes, and does not contain any elements.

The following is a conforming result message:

<nil xmlns='http://www.qworum.com/'>

4.6. The `title` element

A title element briefly describes the fault element that contains it. title elements do not have any attributes, and do not contain any elements.

For example, a financial stock lookup service might return the following result message for an unknown stock.

<fault xmlns='http://www.qworum.com/'>
  <title>Unknown ticker symbol<title>
</fault>

5. Appendices

5.1. Handling non-conforming messages

If a user agent receives a Qworum message that does not conform to the present version of the Qworum specification, then it must use the rules listed below for transforming the received message before handling it:

Messages that are not well-formed XML documents must be transformed into result messages containing a fault element.
Result messages with a non-Qworum root element must be transformed into result messages containing a fault element if the root element has a Qworum element as descendant.
Non-conforming composition messages must be transformed into result messages containing a fault element.
Messages that are neither composition messages nor result messages (i.e. they contain a root element that has the Qworum namespace with a local name different than composition, fault or nil) must be transformed into result messages containing a fault element.

5.2. References

[1] Berners-Lee, T., Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., and Leach, P., Hypertext Transfer Protocol -- HTTP/1.1, RFC 2616, June 1999

[2] Berners-Lee, T., Fielding, R. and Frystyk, H., Hypertext Transfer Protocol -- HTTP/1.0, RFC 1945, May 1996

[3] Rescorla, E., HTTP Over TLS, RFC 2818, May 2000

[4] Berners-Lee, T., Masinter, L., and McCahill, M., Uniform Resource Locators (URL), RFC 1738, December 1994

[5] Fielding, R., Relative Uniform Resource Locators, RFC 1808, June 1995

5.3. Revision history

2008.08.16: composition is removed, the root element of composition messages is now goto.

2008.08.16: The handling of service calls returning a fault has changed: faults now terminate the main service call.

2008.08.16: nothing is renamed to nil.

2008.07.14: Simplifies the handling of non-conforming messages, removes the version attribute from the composition element.

2008.06.04: Introduces a more restrictive definition of conforming parameter elements; modifies the handling of non-conforming parameter elements.

2007.09.06: Initial release.