Join | Sign in

Qworum specification, version 1.0

  1. Introduction
  2. Composing services with Qworum
    1. Multi-phase service calls
    2. Special case: the World Wide Web
    3. Special case: RPC
    4. The user agent as mediator for service calls
  3. Messages
    1. Composition messages
      1. Service calls
      2. Redirections
    2. Result messages
    3. The application/x-qworum+xml media type
    4. The .qrm file extension
  4. Message elements
    1. The http://www.qworum.com/ XML namespace
    2. The call element
    3. The fault element
    4. The goto element
    5. The nil element
    6. The title element
  5. Appendices
    1. Handling non-conforming messages
    2. References
    3. Revision history
    4. Changes between version 0.9 and version 1.0

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.

In this context, Qworum defines a component standard for web applications. Web developers can use Qworum for dividing a web application into several reusable components, which are also called Qworum services. The components that make up a web application do not need to reside all on one single server. 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.

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.

Qworum makes use of a specific web message format, which offers functionality that 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:

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:

  1. a user agent sends a request to a server,
  2. the server performs an operation based on the request and produces a response,
  3. 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:

3.1. Composition messages

Composition messages are used for performing service calls or redirections, as described below.

3.1.1. Service calls

Services may send composition messages to user agents in order to perform one or more service calls. When used for calling services, composition messages convey the following information to the user agent:

As an example, let's suppose that a user agent has received the following composition message from http://www.awebsite.com/: 

<!--
  This composition message allows the end-user to write an e-mail message, 
  and send it.
-->
<qrm:goto href='finished_sending_email' xmlns:qrm='http://www.qworum.com/'> <!-- 5 (order of execution) -->
  <qrm:call href='send_email'>                   <!-- 4 -->
    <email>
      <from>
        <contact>
          <name>My Name</name>
          <email>my.name@email.com</email>
        </contact>
      </from>
      <to>
        <qrm:call href='choose_contact'>         <!-- 1 -->
          <label>E-mail recipient</label>
        </qrm:call>
      </to>
      <subject>
        <qrm:call href='read_line'>              <!-- 2 -->
          <label>E-mail subject</label>
        </qrm:call>
      </subject>
      <body>
        <qrm:call href='read_text'>              <!-- 3 -->
          <label>E-mail body</label>
        </qrm:call>
      </body>
    </email>
  </qrm:call>
</qrm:goto>

The user agent executes this composition message as follows:

Given this algorithm, here is a possible execution scenario for the composition message above:

  1. The user agent (a web browser in this scenario) redirects itself to the contact choosing service by issuing a POST request to http://www.awebsite.com/choose_contact. The request body has the content type application/xml, and contains the following call parameter: 

    <label>E-mail recipient</label>

    The end-user chooses the e-mail recipient through an HTML-based interaction with the service, and the user agent receives the following result message: 

    <contact>
  <name>A Person</name>
  <email>a.person@email.com</email>
</contact>

  2. The user agent redirects itself to the line input service by issuing a POST request to http://www.awebsite.com/read_line. The request body contains the following call parameter: 

    <label>E-mail subject</label>

    The end-user types the e-mail subject, and the user agent receives the following result message: 

    <line>Testing ..</line>

  3. The user agent redirects itself to the text input service by issuing a POST request to http://www.awebsite.com/read_text. The request body contains the following call parameter: 

    <label>E-mail body</label>

    The end-user writes the e-mail body, and the user agent receives the following result message: 

    <text>
  Hi,
  This is a test.
</text>

  4. The user agent redirects itself to the e-mail sending service by issuing a POST request to http://www.awebsite.com/send_email. The request body contains the following call parameter: 

    <email>
  <from>
    <contact>
      <name>My Name</name>
      <email>my.name@email.com</email>
    </contact>
  </from>
  <to>
    <contact>
      <name>A Person</name>
      <email>a.person@email.com</email>
    </contact>
  </to>
  <subject>
    <line>Testing ..</line>
  </subject>
  <body>
    <text>
      Hi,
      This is a test.
    </text>
  </body>
</email>

    The service sends the e-mail message, and immediately returns a result message containing the message which was sent: 

    <email>
  <from>
    <contact>
      <name>My Name</name>
      <email>my.name@email.com</email>
    </contact>
  </from>
  <to>
    <contact>
      <name>A Person</name>
      <email>a.person@email.com</email>
    </contact>
  </to>
  <subject>
    <line>Testing ..</line>
  </subject>
  <body>
    <text>
      Hi,
      This is a test.
    </text>
  </body>
</email>

  5. Finally, the user agent redirects itself to the next phase of the service which sent the composition message, by issuing a POST request to http://www.awebsite.com/finished_sending_email. The request body has the content type application/xml, and contains the following phase parameter: 

    <email>
  <from>
    <contact>
      <name>My Name</name>
      <email>my.name@email.com</email>
    </contact>
  </from>
  <to>
    <contact>
      <name>A Person</name>
      <email>a.person@email.com</email>
    </contact>
  </to>
  <subject>
    <line>Testing ..</line>
  </subject>
  <body>
    <text>
      Hi,
      This is a test.
    </text>
  </body>
</email>

3.1.2. Redirections

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

For example, 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 contain the following phase 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>
  <status>Processed</status>
  <transaction>185896449654</transaction>
</payment>

If the phase parameter is absent, then a GET request is issued. For example, 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/' />

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:

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 supports Qworum version 1.0, then the Accept headers of the HTTP requests it generates must include the following:

application/x-qworum+xml;version=1.0

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

Accept: application/x-qworum+xml;version=1.0,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, the root element of the result message will replace the call element in the composition message.

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 which is one of the following:

call elements may contain zero, one or more title elements.

Here is a composition message that uses the call element (see the section 3.1 for more examples):

<--
  This composition message allows an e-commerce site to call 
  a secure payment processing service.
-->
<qrm:goto href='checked_out' xmlns:qrm='http://www.qworum.com/'>
  <qrm:title>Receive the result of the payment processing call</qrm:title>
  <qrm:call href='https://www.apaymentprocessingsite.com/process_payment'>
    <qrm:title>Perform the payment processing call</qrm:title>
    <!--
      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 could not complete successfully.

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 zero, one or more title elements.

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 is one of the following:

goto elements may contain zero, one or more title elements.

See the section 3.1 for more composition message examples.

4.5. The nil element

The nil element indicates that a service call was completed successfully, 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 in 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 goto, call or fault element that contains it.

title elements do not contain any elements. They may have zero, one or more sibling title elements. They have an optional lang attribute which indicates the natural language which is being used. Accepted values for this attribute are described in the section 3.10 of the HTTP/1.1 specification.

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

<fault xmlns='http://www.qworum.com/'>
  <title lang='de'>Unbekannte Aktie<title>
  <title lang='fr'>Code inconnu<title>
  <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:

  1. Messages that are not well-formed XML documents must be transformed into result messages containing a fault element.
  2. 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.
  3. Non-conforming composition messages must be transformed into result messages containing a fault element.
  4. 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.06: Initial release.

5.4. Changes between version 0.9 and version 1.0

The changes mainly concern the use of call and title elements, as described below: