Waterken^TM Web

HTTP Binding

2003-03-22

This specification defines how the Waterken^TM Web Abstract Messaging Protocol is bound to HTTP. The binding leverages the existing WWW infrastructure.

Abstract

The <http://waterken.com/amp/Envelope> schema is mapped to the HTTP Request and Response structures. Where appropriate, HTTP status codes are associated with response node types.

Overview

Design goals

WWW browser as a human-to-messaging protocol interface

The Waterken^TM Web calculus defines an interface model based on a web of typed nodes. The HTTP binding must be defined such that a User Interface (UI) can be constructed for an application by defining an HTML rendering of the node types. This HTML rendering acts as a "message generator", allowing the user to send the messages needed to traverse the web or to invoke a target lambda.

Supporting this type of HTML user interface means that each feature of the Waterken^TM Web Abstract Messaging Protocol must be exposed in a way that is supported by existing WWW browsers.

Document Exchange Model

The WWW is based on Document Exchange Model (DEM) document retrieval. In the DEM, documents are retrieved by dereferencing a URI. The existing WWW infrastructure is optimized to support these DEM queries by caching GET requests. Much of the existing WWW software also only supports DEM document retrieval. For example, XSLT only supports document retrieval through its DEM style document() function.

To support interoperation with other HTTP based software, the HTTP binding must encode all the information for a Waterken^TM Web calculus GET operation in a URI.

Homeless clients

Most existing WWW client software does not support any server functionality. For example, a typical WWW browser does not allow a web site to send a delayed response to the browser. In addition to this lack of software support, many clients are behind a network firewall that prevents all inbound TCP/IP connections. Most WWW clients are operating as if they have no home address at which to receive return mail.

To accommodate homeless clients, the HTTP binding must match the request-response style defined by HTTP.

Description

This section describes how the HTTP binding meets the network protocol requirements specified in the Waterken^TM Web Abstract Messaging Protocol specification.

Locating the server host

HTTP uses the http URI scheme for locating sites. The http URI scheme either directly specifies the site IP address or a hostname to be resolved using the DNS.

Server authentication

Server authentication must be provided by a network protocol running underneath HTTP, such as SSL.

Transport secrecy

Transport secrecy must be provided by a network protocol running underneath HTTP, such as SSL.

Sending a request

Each request <http://waterken.com/amp/Envelope> is transported in a separate HTTP Request.

The 'op' is encoded in the Request-Line Method.

The 'src' URI is encoded in the Request-Line Request-URI and the Host request header.

The Request-URI query string MUST be encoded according to the application/x-www-form-urlencoded Media-Type. The 'path' is encoded in a name-value pair with name "path". The GUID from the 'reply_to' URI is encoded in a name-value pair with name "mid".

The 'args' are encoded in the HTTP Request message-body. The message-body is an encoded node list. Each node in the node list is the corresponding argument.

Receiving a response

The response <http://waterken.com/amp/Envelope> is encoded in the corresponding HTTP Response.

The 'op' is defined to be POST, so is not explicitly encoded.

The 'src' URI is implicit based on the position of the HTTP Response in the HTTP stream, so is not explicitly encoded.

The 'path' is defined to be empty, so is not explicitly encoded.

A response has no 'reply_to', so none is encoded.

The 'args' are encoded in the HTTP Response message-body. The message-body is the encoded single return node.

Required HTTP Status-Codes

The default Status-Code for an HTTP Response is 200. Depending upon the return node, a more specific Status-Code MUST be used.

Other appropriate HTTP Response Status-Codes SHOULD be used to report errors in decoding a Request.

Required Media-Types for encoding a message

A server may support a variety of Media-Types, but is required to support at least the Media-Types listed here.

This Media-Type indicates that the message-body is encoded using the XML surface syntax of the Waterken^TM Doc Document Model.

Optional Media-Types for encoding a message

If a server supports any of the optional Media-Types listed here, it MUST do so in a way compliant with this specification.

This Media-Type indicates that the message-body is encoded using the www-form surface syntax of the Waterken^TM Doc Document Model.

This Media-Type indicates that the message-body is encoded using the code surface syntax of the Waterken^TM Doc Document Model.

Examples

GET /example/cl3d5xjtlvjtba2aqceks6ymwe?path=balance/ HTTP/1.1
Host: server.waterken.com
Accept: text/xml

HTTP/1.1 200 OK
Content-Type: text/xml;charset="UTF-8"
Content-Length: 50

<doc schema="http://waterken.com/Integer">3</doc>

HTTP/1.1 404 Not Found
Content-Type: text/xml;charset="UTF-8"
Content-Length: 0

POST /example/cl3d5xjtlvjtba2aqceks6ymwe?path=withdraw/&mid=3u6k4dlbitylyuplg5ubyzacwy HTTP/1.1
Host: server.waterken.com
Accept: text/xml
Content-Type: text/xml;charset="UTF-8"
Content-Length: 69

<list>
    <doc schema="http://waterken.com/Integer">1</doc>
</list>

HTTP/1.1 200 OK
Content-Type: text/xml;charset="UTF-8"
Content-Length: 143

<doc schema="http://waterken.com/doc/pointer/Link">
    <target>https://server.waterken.com/example/o4zpok3s3ud3acx3jis3nawct4</target>
</doc>

EXPECT /example/cl3d5xjtlvjtba2aqceks6ymwe HTTP/1.1
Host: server.waterken.com
Accept: text/xml
Content-Type: text/xml;charset="UTF-8"
Content-Length: 99

<list>
    <doc schema="http://waterken.com/uri/URI">http://waterken.com/iou/Account</doc>
</list>

HTTP/1.1 200 OK
Content-Type: text/xml;charset="UTF-8"
Content-Length: 143

<doc schema="http://waterken.com/doc/pointer/Link">
    <target>https://server.waterken.com/example/cl3d5xjtlvjtba2aqceks6ymwe</target>
</doc>

EXTRACT /example/cl3d5xjtlvjtba2aqceks6ymwe?path=balance HTTP/1.1
Host: server.waterken.com
Accept: text/xml

HTTP/1.1 200 OK
Content-Type: text/xml;charset="UTF-8"
Content-Length: 143

<doc schema="http://waterken.com/doc/pointer/Link">
    <target>https://server.waterken.com/example/6xexrsaiwbt63742pkfex6bqra</target>
</doc>

SETTLE /example/6xexrsaiwbt63742pkfex6bqra HTTP/1.1
Host: server.waterken.com
Accept: text/xml
Content-Type: text/xml;charset="UTF-8"
Content-Length: 170

<list>
    <doc schema="http://waterken.com/doc/pointer/Link">
        <target>https://client.waterken.com/example/3xe5w7hgenjdbuqll3b5tknqbm</target>
    </doc>
</list>

HTTP/1.1 200 OK
Content-Type: text/xml;charset="UTF-8"
Content-Length: 46

<doc schema="http://waterken.com/Void"></doc>

Copyright 2002 - 2003 Waterken Inc. All rights reserved.