web-calculus

HTTP Binding

2006-02-03

This specification defines the HTTP binding of the web-amp. The binding leverages the existing WWW infrastructure.

Abstract

The <http://web-calculus.org/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 closure.

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://web-calculus.org/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 query string URI component is encoded according to the application/x-www-form-urlencoded Media-Type. The unguessable GUID identifying the target edge is encoded in a name-value pair with name "key".

Sending a request

Each request <http://web-calculus.org/amp/Envelope> is transported in a separate HTTP Request.

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

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

The 'mid' is encoded in a query string 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. If the response requires special handling by the client, an alternate response code, specified by the table below, MUST be used.

The 404 and 410 responses SHOULD contain an informational response for consumption by a human client. All other client software MUST ignore any message-body and treat the Status-Code as canonical.

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 web-calculus 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 web-calculus Document Model.

This Media-Type indicates that the message-body is encoded using the code surface syntax of web-calculus Document Model.

Examples

GET /test/?key=bsnb-5skf-p3sm HTTP/1.1
Host: www.example.com

HTTP/1.1 200 OK
cache-control: max-age=31536000
content-type: application/xml
content-length: 556

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl"
    href="/xsl/http/yurl.org/Expert-define.xsl"?>

<list>
<doc schema="http://yurl.org/Expert-define">
<super schema="http://web-calculus.org/ref/Declaration">
<in schema="http://web-calculus.org/schema/parameter/Immutable">
<category>http://web-calculus.org/string/String</category>
</in>
<out schema="http://web-calculus.org/schema/parameter/Lambda">
<type>http://yurl.org/Author-assign</type>
</out>
<error>http://web-calculus.org/content/Collision</error>
</super>
</doc>
</list>

HTTP/1.1 404 Not Found
content-type: application/xml
content-length: 162

<?xml version="1.0" encoding="US-ASCII"?>
<?xml-stylesheet type="text/xsl" href="/404.xsl"?>

<list>
<doc schema="http://web-calculus.org/amp/NotFound"/>
</list>

POST /test/?key=bsnb-5skf-p3sm&mid=tm635augvad5tft3l57uchjanq HTTP/1.1
Host: www.example.com
Content-Type: application/xml
Content-Length: 77

<list>
<doc schema="http://web-calculus.org/string/String">foo</doc>
</list>

HTTP/1.1 200 OK
content-type: application/xml
content-length: 243

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl"
    href="/xsl/http/web-calculus.org/pointer/Link.xsl"?>

<list>
<doc schema="http://web-calculus.org/pointer/Link">
<target>./?key=5xmx-h4uj-bgtr</target>
</doc>
</list>

HTTP/1.1 200 OK
content-type: application/xml
content-length: 326

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl"
    href="/xsl/http/web-calculus.org/content/Collision.xsl"?>

<list>
<doc schema="http://web-calculus.org/ref/Smashed">
<reason schema="http://web-calculus.org/content/Collision">
<super schema="http://web-calculus.org/Error"/>
</reason>
</doc>
</list>

Copyright 2002 - 2006 Waterken Inc. All rights reserved.