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.


6 Comments

hugh winkler said:

Hey Mark, I left some comments at http://hughw.blogspot.com/2005/07/reliable-post.html. My main concern was that POE changes the semantics of 405 a little. I can’t really see very negative impacts from that, except that a browser user might interpret 405 as a failure. Still, it seems possible to do POE and return the same success code and entity as the first successful POST did, and not overload 405. Have I missed something?

Saturday, July 9 2005 at 11:15 AM

Stefan Tilkov said:

The link to the POE draft is 404 now.

Thursday, November 30 2006 at 1:31 AM

Jan Algermissen said:

Hi Mark,

a question: how does the server detect that some POST is actually a re-POST? I fail to find any means that identify a POST request. Or is the POE Resource non-reuasable and will change upon a new GET to e.g. the basket?

Jan

P.S. Since I first came across the ‘POE’ draft I have been wondering whether General Ripper inspired the name :-) http://www.indelibleinc.com/kubrick/films/strangelove/ http://www.indelibleinc.com/kubrick/films/strangelove/images/poe.jpg

Sunday, January 21 2007 at 9:41 AM

Carl Nobile said:

In a RESTful interface POST is used when the client or client=agent does not know the URI, meaning the server needs to supply it. I think this you have shown in your draft. However, this is not only true when creating a new URI but also when updating/append a URI. This indicates a second case where one would not want to create a new URI, but update it with a second POST. How would POE work in this case?

Sunday, March 16 2008 at 6:48 AM