This post originated from an RSS feed registered with Java Buzz
by Bill de hÓra.
Original Post: "Just" use POST
Feed Title: Bill de hÓra
Feed URL: http://www.dehora.net/journal/atom.xml
Feed Description: FD85 1117 1888 1681 7689 B5DF E696 885C 20D8 21F8
Tim Bray: "But maybe Joe needs a bigger club, because I have to admit
that limiting myself to GET and POST just doesn’t cause me that much
heartburn."
I get asked a lot about PUT v POST, as do other people associated with REST based design. The question come up online frequently as well (it's a regular topic on the rest-discuss and atompub lists). Usually it's in the context of updates via forms posting or how to change just a few data fields. "How do I change the title?" is very common and valid use case. Forms posting is easy to code - almost all deployed client and server libraries support (and are often optimised for) forms posting.
The pro-REST answer is to use PUT. PUT means update the resource with this entity, which tends means "overwrite". Now think for a moment about how that works for things like tags in a blog post - if I leave the tag out, am I saying remove it? Ignore it? Do I have to echo back all the data so it doesn't get scrubbed? On the server side, PUTs to resources involving embedded lists (eg tags in Atom/RSS entries) tend to result in ugly code on the when the backing system is an RDBMS, or the representation is any "joined" structure in the persistence layer - they'll have to diff what's persisted against what's sent, which means a "select for update" pattern. A double for loop is a sure sign you've hit this probelm. Sure you can store the entity straight to disk - now you have N indexing problems. The database-as-implementation-detail isn't a realistic option for millions of web developers.
So PUT often feels wrong or contorted to developers who literally want to mod a couple of fields. Hence PUT is much less popular in the wild than forms posting (all aside from the fact that PUT is excluded from HTML4 forms). In other words, people tend to see PUT as a heavyweight, sucking, POST. In turn they "just" use POST+forms.
Are we done? Unfortunately, no.
So when does PUT v POST actually *matter*? It matters, as far as I can tell, when your resource stands for a collection, which is very common - folders, albums, feeds, collections, blogs, tagclouds, orders, a shopping cart - any list based structure.
Let's take AtomPub as an example - to add something to a collection using AtomPub, you use POST:
POST /collection host :example.org content-type: image/png
...binary...
Updates to collections are undefined in AtomPub. But let's ask, how would we do that? Imagine we just want to changed the title - why bother a PUT of an atom feed - isn't that verbose, inefficient and stupid? We could "just" use a form post instead:
POST /collection host :example.org content-type: application/x-www-form-urlencoded
&title=foo
Ahh. Boom. Updating the collection in this way uses the same verb as the adding to the collection. How to tell the difference in client intent? The answer here for most people, will be to use the fact that forms posting has a certain media type so the media type "qualifies" the operation - this definitely isn't REST style as the verb is no longer uniform. This is not an abstract concern - there'll be a big switch in the code somewhere, exactly the kind of thing programmers hate. Remember AtomPub servers aren't limited to blog posting - they can accept any media type they declare support for. One workaround could be that if the client sent a corresponding "ID":
POST /collection host :example.org content-type: application/x-www-form-urlencoded
the server could detect that the ID is present. It feels funky though, aside from having to map the field/keys in your precious snowflake format into forms parameters
Perhaps we shouldn't have skipped collection updates in AtomPub as it would have made the overall pattern clearer - POST can't be used in the general sense for updates to collections, hence PUT is the only uniform approach to updating content.
Fwiw, like Tim, I can live with the forms POST option, to either update a collection or perform a partial write. But think about it for a bit - switch on type is a fairly ugly workaround. Not quite RPC, but problematic. Blog entries in turn are often collections (containing media), as are the folders you find in WebDAV and so on. It's not a problem specific to AtomPub.
So when you ask a pro-REST person about why not "just use forms" for
partial updates instead of having to write out the entire data to send
to the server via PUT, and they go "uhm, uhm,...", this is the kind of
design kludge they're thinking about. Maybe you could PUT a form as a workaround for partials - I think that could work better than POST or having special "edit" URIs for anything collection-like. But as far it goes as I'm not sure we in the pro-REST community have a good general answer or design pattern for partially updating a resource. Until we do, I predict people will tend drop down to using forms posting as it's the easiest thing to do with deployed client libraries and web frameworks. That or define some other specialised media type for partial updates.
Previous Topic
