Tarawa Interface Definition

revised April 26, 2003

Introduction

Tarawa is an Web server API, similar to Java's Servlet interface; it provides an abstraction of the Web server that allows you to easily write Web applications, without knowing the details of the HTTP protocol. Unlike other HTTP APIs, Tarawa is designed to encourage applications to align their object model with the interface they expose as Web resources. It does this by allowing you to model resources and representations as objects and HTTP methods as object methods.

In Tarawa, a Resource is both an object in code and an identifiable resource on the Web; in other words, it is an instance of a class that's identifiable by a URI. Resources are managed by an instance of a Server, which dispatches requests to Resources as appropriate.

When a Server dispatches a request to a Resource, it will call the method corresponding to the HTTP method (e.g., GET) to perform the appropriate processing. The return value is a string, that, in combination with method metadata, will be used to form a Representation, which is the basis of the response to the client.

Optionally, content negotiation methods may be called to transform the response as appropriate. The Server will then package the representation in a Response and send it back to the client.

This document is an overview of the classes in the tarawa package; although it is Python-specific, it should be possible to implement with minimal changes in other object-oriented languages. For an overview of how Tarawa should be used, see the tutorial. This document does not cover the extensibility interfaces of Tarawa (e.g., for accessing the HTTP pipeline).

Class Resource

A Web resource, identified by a URI. Resources expose an interface defined by some combination of the GET, PUT, DELETE and POST methods, whose semantics are documented in HTTP/1.1. It also exposes hooks for content negotiation and state management.

Some method names include [media_type], which is replaced with the appropriate Internet media type string, with all non-alphanumeric characters transformed to '_'; e.g., "text/html" would become "text_html", while "application/rss+xml" would become "application_rss_xml".

Also, methods which implement HTTP methods (e.g., GET) and should have a docstring (__doc__) beginning with a line containing a Content-Type HTTP header, which indicates the media type of the representation that will be returned by successful execution of the method. The docstring may contain other headers in a similar fashion; any documentation intended for humans should follow a blank line.

Resource should not be instantiated directly, but subclassed to an application-specific object; e.g., DirectoryIndex(Resource).

Methods

string GET (mapping query)

Called upon a HTTP GET; query is the URI query component. Successful responses should return a string that represents the resource's state; it may also raise a http.statusMessage exception.

string PUT (mapping query, http.message.Request representation)

Called upon a HTTP PUT; query is the URI query component and representation is the request. Should return a string containing a status message, or raise a http.statusMessage exception.

string DELETE (mapping query)

Called upon a HTTP DELETE; query is the URI query component. Should return a string containing a status message, or raise a Response exception.

string POST_[media_type] (mapping query, http.message.Request representation)

Called upon a HTTP POST with a [media_type] request payload; query is the URI query component and representation encapsulates the request. Should return a string representing the resource's state, or raise a http.statusMessage exception.

Resource getChild(string name)

Called if no appropriate child Resource can be found in the children mapping; should return a subclass of Resource (not an instance) as appropriate for the name parameter.

By default, this method will return a NotFound status exception.

void storeState()

Store the resource state in an application-specific manner; e.g., write to a database. Called during instance construction.

void restoreState()

Read stored resource state in an application-specific manner; e.g., from a file. Called during instance destruction.

Attributes

mapping children

A dictionary of the Resources(subclasses, not instances) that are contained by this Resource, keyed by path segment. For example, if the Resource FooResource with the path "/foo" had a child BarResource with a path of "/foo/bar", FooResource.children would be {"bar": BarResource}.

Resource parent

The parent Resource of this Resource (read-only).

string name

The most specific path segment identifying the resource; e.g., "baz" for "http://www.example.com/foo/bar/baz" (read-only).

Class NegotiatedResource (extends Resource)

A Resource capable of Content Negotation of media types. Negotiation methods should have a docstring containing a Content-Type header indicating the output media type, just as HTTP methods do.

Methods

string [media_type]_TO_[media_type] (string body)

Translate between two media types. Called automatically to transform the output of the GET, PUT, DELETE, POST_[media_type] and POST methods before serving to the client, as appropriate. May also raise a http.statusMessage exception.

Class Server

A Web server. Should not be instantiated directly, but subclassed to accommodate the server environment; e.g., CGIServer(Server), ModPythonServer(Server), MedusaServer(Server), etc.

Methods

void __init__ (Resource rootResource, string rootURI)

Constructor, to be called with a Resource that acts as the root, along with a corresponding absolute URI.

void serve()

Initialize the server and begin servicing requests.

About this Document

Thanks to Mark Baker, Aaron Swartz and Mike Ciavarella for their comments, suggestions and extensive review. Any design flaws, errors or omissions are the author's, not theirs.

This work is licensed under a Creative Commons License.