mark nottingham

Nevermore

Monday, 21 March 2005

HTTP APIs

A while back, I wrote up a description of a pattern for avoiding messages like “ click submit only once.” I didn’t do much after that, because I’ve been a bit busy, and because I wanted to do some implementation of a more general HTTP framework before I wrote a more formal document.

One delay led to another, and to make a long story short, I never got around to writing that specification… until now.

Why now? The short answer is that Bill de hÓra’s effort, HTTPLR, gave me a good reason to overcome inertia. I think Bill is spot-on in many ways, but I wanted something smaller and looser; while Bill describes a full-on protocol, I wanted something that’s more of a lightweight, reusable pattern.

I was tempted to give specific feedback to Bill along these lines, but it’s pretty clear that he has something specific in mind for HTTPLR, and it’s not clear that the two approaches are mutually excusive. So, I documented what I’ve been thinking.

Post Once Exactly

My attempt is called Post Once Exactly, or POE for short. It isn’t so much an HTTP extension than it is a pattern of use; much as described in the original article, clients can take advantage of certain properties of the resource to figure out if their POST request has been successful.

The major change from what I previously described is that a pair of HTTP headers have been added; one to advertise that a particular resource is a POE resource, and therefore will honor certain guarantees, and the other advertises that the client can use that information, so that the server can adjust its responses accordingly.

This isn’t to say that HTTP headers have to be used; this information could be in a format-specific markup extension, or in an external file altogether. In fact, they aren’t necessary at all; the pattern can be used without them by prior agreement.

Likewise, the headers are there to help automated retries; that isn’t to say that automation is required. A site can use this pattern without any explicit support for it on the User-Agent, as the user themselves can be instructed to retry requests and receive meaningful feedback.

As always, feedback and suggestions appreciated (especially from Bill!).

P.S. I am working on that implementation; stay tuned.