Tarawa design notes

Motivation and Influence

I've been interested in API design for some time, specifically those that constrain their users to force them to "the right thing" both in the direct use of the API, as well as in their overall application architecture. Tarawa is an effort to apply this goal to an HTTP API.

Tarawa was most obviously inspired by the REST architectural style, as documented by Roy Fielding. REST attempts to explain the design choices that were made by the HTTP Working Group over its history, and it only seems fitting that an API for HTTP should be designed in harmony with it. It was also influenced, possibly subliminally, by Tim Berners-Lee's various talks and papers about "Web-izing" languages, specifically Python.

Design Goals

One of the first things many people notice about Tarawa is that the method handling the HTTP method (what a mouthful) doesn't have much context about the request, in terms of HTTP headers.

Additionally, both the dispatch for content negotiation and response headers associated with a method are static; you can't dynamically dispatch to content types that were'nt known at design time, for example, and you are forced to raise an exception to dynamically associate headers with a response.

All of this is due to a combination of design and pragmatism. Tarawa attempts to abstract as many protocol-related decisions away from the developer as possible; they are constrained to an interface where they can only talk about the semantics of their application in terms of URIs, media types and HTTP methods.

Although exposing the HTTP pipeline allows these applications to be built in Tarawa, it is not a design goal to enable every Web application to be Tarawa-based; instead, it is to enable a fairly broad class of application, where the types accepted and produced are known at design time.

API Choices

The use of docstrings for metadata is pragmatic; once a better syntax for function attributes is defined in Python, Tarawa will switch over to them.

Future Directions