Waterken^TM Web

HTTP Binding

2003-12-22

This specification defines the HTTP binding of the web-amp. 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 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 web-amp 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.

Support for the HTTP GET method is required for interoperability with other HTTP applications.

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

The web-amp HTTP binding has three main components. The http: URL scheme is extended to support the properties of a capability URL. The HTTP Request and Response structures are mapped to the <http://waterken.com/amp/Envelope> schema. HTTP status codes are associated with response node types.

Capability URL

The web-amp specification lists the requirements for a capability URL.

The HTTP protocol does not itself support server authentication and encryption. These capability URL features must be provided by another HTTP extension, such as httpsy:, or https:.

The unguessable GUID identifying the target is encoded in the last segment of the URL path. The GUID is the portion of the segment before the first occurrence of the '.' character, or the whole segment if there is no '.' character. The grammar for the GUID segment is:

    guid-segment = guid [ '.' *pchar ]

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 'target' 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 'mid' is encoded in a name-value pair with name "mid".

The 'arg' 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.

The operation return is encoded in the HTTP Response message-body.

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 MUST 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 HTTP/1.1
Host: server.waterken.com
Accept: text/xml

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

<doc schema="http://waterken.com/iou/Account">
    <brand schema="http://waterken.com/doc/pointer/ID">
        <target>http://localhost/id/qfpppfmwvlasandctjcwndqbbe</target>
    </brand>
    <balance schema="http://waterken.com/doc/pointer/Link">
        <target>bjg2iyk57k6dekiltsfv2ngaom</target>
    </balance>
    <buy schema="http://waterken.com/doc/pointer/Link">
        <target>xqfcxgmlzihncztcwo4izisn54</target>
    </buy>
    <sell schema="http://waterken.com/doc/pointer/Link">
        <target>oadiw2p4dqoao27oxe4sibsupy</target>
    </sell>
</doc>

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

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

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

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

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

<doc schema="http://waterken.com/doc/pointer/Embed">
    <target>o4zpok3s3ud3acx3jis3nawct4</target>
</doc>

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

<doc schema="http://waterken.com/adt/promise/Smashed">
    <reason schema="http://waterken.com/iou/InsufficientFunds">
        <super schema="http://waterken.com/Error"/>
    </reason>
</doc>

Copyright 2002 - 2003 Waterken Inc. All rights reserved.