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 comes up online frequently as well (eg 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 of an entry?" is a very common and valid use case. Forms posting is easy to code to and highly portable - 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". Let's 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 or ignore it? On the server side, a PUT to a resource involving embedded lists (eg tags in Atom/RSS entries) tends to result in ugly code when either 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 for 99% of people means a "select for update" pattern (a double for loop cross-referencing the posted tag list with the database tags is a sure sign you've hit this problem). Yes, you can store the entity straight to disk or use a non-relational architecture - but now you have N indexing problems, something a relational database "just" solves for the 99.9% of developers who don't have a megadata problem.
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.
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...
Easy, and you can update that uploaded object later via PUT. Updates to the collections themselves are undefined in AtomPub. But let's ask, how would we do that? We could PUT the Atom feed (san the contained Entries) back to the collection URI. So imagine we want to change only the title - isn't an entire PUT of an Atom feed (san the contained Entries) verbose, inefficient and stupid for that simple usecase? 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 specific media type - so the media type "qualifies" the operation. This definitely isn't REST style, as the verb is no longer uniform; at the same time it's not an abstract concern - there'll be a big switch in the code somewhere that looks for the media type - exactly the kind of thing good programmers hate. Let's remember that AtomPub servers aren't limited to blog posting - they can accept any media type they declare support for, adn thus can act as generic upload systems (if you have a stable network, more on that another time).
One workaround could be that if the client sent a corresponding "ID", like this:
POST /collection
host :example.org
content-type: application/x-www-form-urlencoded
&title=foo&id=http%3A%2F%2Fexample.org%2Fid%2Fefgfeacbe
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
Speaking as a member of the IEFT WG, perhaps we shouldn't have skipped collection updates in AtomPub as it would have made the overall constraint clearer - POST can't be used in the general case for updates to collections, ergo PUT is the only uniform approach to updating their content. On the other hand lots and lots and lots of people don't, won't (and sometimes can't) care about REST/HTTP/AtomPub arcana. So some part of me thinks we need patterns and practices to help developers jfdi.
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 and most portable approach for deployed client libraries and web frameworks. That or define some other specialised media type for partial updates.
35 Comments
Very nice post -- thanks.
In our system, every collection is also available as an entry in a "collections" collection. Updating is simply GET/PUT on the proper entry. I don't see anyway around that in AtomPub, where the "entry" is king and feeds (not collections) are secondary. So everything has an atom:entry representation.
For partial updates, we settled on a local atom extension: an attribute "x:edit-id" on any element in the entry that is exposed as an editable sub-resource to the entry (AND that has text content -- we happen to use categories w/ text content regularly which some will frown on). The value of x:edit-id is simply the URI for that resource -- handy for AJAX "delete" as well as "put" (mostly "put"-ing text/plain). For regular full-resource AtomPub PUT, we settled on: expose an atom extension link that offers a JSON version of the atom:entry. On form submit, grab the json and diff it against current values in the form, then run it through a little javascript template function we have to serialize out atom+json to atom+xml and let XHR "put" it back to the AtomPub endpoint (the "edit" link).
This all seems a bit complex, but once the pieces are in place it is quite clean to work with. I am not opposed to form posting w/ x-www-form-urlencoded, but every developer ends up doing it differently and you end up with RPC-ish/hard-to-maintain apps.
This is all just by way of a plug for Atom/AtomPub -- I do think it is widely applicable and offers a nice set of constraints if one is willing to address a few pain points. And who knows, maybe some of these techniques will get wider play and make browser-based AtomPub easier for everyone.
I like to think I'm pro-REST, but I would have designed it differently. Ask the collection to tell you how to change it's title, and how to add a new entry, and those would be two different URLs that can both use the same method (or not). With a browser in the front this pattern would feel really natural.
If it feels funky, I think it has something to do with the combination of CRUD around the resource in addition to REST.
I don't know Atom, but I agree with Assaf--the resource should tell you how to update it.
Seems like it should be as simple as:
PUT /collection/title
host: example.org
content-type: text/plain
foo
Sascha: "A simple decision for us to use POST or PUT is technology based. In Java ME (MIDP 2.x) PUT is not obligatory. In that case..."
Thanks, I know the limitations of mobile tech, as well as the limitations of tech like HTML4 (where PUT is not available at all). The point is there aren't patterns to deal with the limitations. Fobbing it off to semantics doesn't work for me, not the least because having to write per client device servers is nutso.
Mike: "PUT /collection/title"
As long there's no Entry in that collection, with that URI...
Assaf: "I like to think I'm pro-REST, but I would have designed it differently. Ask the collection to tell you how to change it's title"
How do I ask, in a way that is more uniform than using a form?
Excellent post. Dunno whether any pingback thingy works, but I gave a shot out from:
http://broadcast.oreilly.com/2009/02/...
What about HTTP PATCH ?
https://datatracker.ietf.org/drafts/d...
Bill: "the media type "qualifies" the operation [...] there'll be a big switch in the code somewhere [...] Remember AtomPub servers aren't limited to blog posting - they can accept any media type they declare support for."
Isn't media resource posting one of those big switches? so POST in AtomPub doesn't appear to be uniform (for strictest definitions of uniform): it performs two kind of appends.
I totally agree with everything you've just said Bill - good post. For me the big win of PUT is knowing its idempotent where with POST unless you know exactly about a specific service you've no idea.
However if you want to build a RESTful service that allows web browsers to integrate with it (which is kinda handy :-) which have to rely on just GET/POST how about a solution to your example being...
For inserting to the collection...
POST /collection
For updating an item in the collection, use a different URI
POST /collection/someId
The both lose the idempotent feature of PUT unless you use the POST-returns-redirect-unique-url trick that Atom uses but you can still use that with POST
More uniform? How do we measure degrees of uniformity?
As far as REST is concerned, if you have a generic content type that can express hypermedia, you're fine. HTML does that. Atom to some extent (links), and could definitely benefit from actions. In fact, a message that tells you how to update an entry, add a collection, etc by expressing the action is more self-describing than one that sends you look at the specification. I believe self-describing is part of the uniform interface REST talks about.
POST is also superior to GET as a partial CSRF countermeasure
http://en.wikipedia.org/wiki/Cross-si...
Google's AtomPub feeds allow you to set the header X-HTTP-Method-Override, whose value can be PUT or DELETE, in order to break out of sandboxes that don't allow these verbs. So if you POST with the appropriate header, the operation is conceptually a PUT or DELETE as the case may be, and is remapped at a low level.
Disclaimer: I don't speak for Google, and I'm only restating what's a matter of public record anyhow.
It's a bit astronautical, but I kinda agree with Assaf. The question of granularity : if the title is significant enough that you might want to change it independently of other pieces of data, then it should probably have its own URI.
Thank you for the article! Good luck!
http://www.magentocommerce.com/boards...
http://cgi3.ebay.com/ws/eBayISAPI.dll...
http://www.vimeo.com/buyviagrahq
http://www.playlist.com/blog/entry/12...
Herbal for men
Links of London( http://www.linksgiftstore.com )
Links London ( http://www.linksukstore.com )
Links of London( http://www.toplinkslondon.com )
<p><a href=http://www.showcu.com><b>MBT Anti Shoes</b></a> have been known as "the world's smallest gym." Since they increase muscle activity, strengthening and toning of the leg, buttock, stomach and back muscles takes place during everyday activities like walking and standing.
Since celebrities like Cher, Gwyneth Paltrow, and Heidi Klum have reportedly added <a href=http://www.showcu.com><b>Discount MBT Shoes</b></a> to their shoe collection,<a href=http://www.showcu.com><b>Cheap MBT Shoes</b></a> have received a lot of press . Their unique design has supposedly help wearer's tone up, lose weight, and even smooth cellulite, and it has garnered the brand a lot of attention as well.
Shop your <b>MBT Anti Shoes</b> on Showcu of <a href=http://www.showcu.com/mbt-lami-shoes-c-1.html><b>MBT Lami Shoes</b></a>.We are the stockist of <b><a href="http://www.showcu.com">Timberland Boots</a> </b>.Our <b>Anti Gravity Shoes</b> Sale in huge stock.You can enjoy Free Shipping on our <strong><a href="http://www.showcu.com">Timberland Shoes</a></strong> and <b><a href=http://www.showcu.com/mbt-walking-shoes-c-2.html>Walking Shoes</a></b>.Buy Now!</p>
<a href=http://getanabolics.com><img>http://www.mtv.com/onair/truelife/assets/flipbook_season8/steroids/tl_steroids_01.jpg</img></a>
Searching for info on anabolic steroids pills? Learn to body build and stay fit without hurting your health. There are many <a href=http://www.bodybuildingsupplements.350.com>body building</a> articles to navigate. It's hard finding good content.
<a href=http://www.gather.com/viewArticle.action?articleId=281474978049542>Purchasing steroids</a> on the open blackmarket can be dangerous. We strongly advise all weight trainers who use <a href=http://bestbodybuildingsupplements.webnode.com>anabolic steroids</a> if your into <a href=http://bodybuildingsupplements.onsugar.com/Best-Steroids---GetAnabolicscom---Health-Bodybuilding-Fitness-7422470>health fitness</a> then your going to want to check out. <a href=http://legalsteroids.wikidot.com/>Metabolism Steroids</a> can reduce your body. <a href=http://www.getanabolics.com/>Body building suppliments</a> are a key ingredient to improving your fitness.
There are many portals that talk about steroids and anabolics. Check out <a href=http://getanabolics.com/>Bodybuilding Suppliments</a> for more info.
100226SLZZQ Set some royalty your light night set, all day, for example, you can run this ugg classic short boots discount , no matter how boring your attachments may seem, this package is guaranteed to you to set really amazing and complex uggs classic cardy boots saw a day.This package does not in fact is lame, however, it is some lame, clarify this in addition to other casually elegant fabric bag. It has been all throughout the mosaic keeps this wallet gives off impressive glitzy effect of an appeal. This too can be drag-and-diploma by locking firmware Louis Vuitton handbags on sale gold tone series in front of the open and will display a small pocket replacing it with the logo exposed skin. As a fully what Chloe Designer Louis Vuitton Handbags see more these days, it also comes with a gold tone chain shoulder strap.Because this ugg bailey button boots - Lame shoulder bag seem sumptuousdining has been estimated to apply the General. But the luxuriousness of course you can to do this cheap ugg classic mini boots . http://www.uggbootssaleonline.com
Greetings, I'm Paul Gamache
[URL=http://www.sandiegoacupunctureandherbs.com/][IMG]http://www.cosmosmagazine.com/files/imagecache/news/files/20070925_acupuncture.jpg[/IMG][/URL]
Paul Gamache has patients in San Diego County who have menstrual disorders, and more. His devotion, and belief in the consideration of the [I]whole person[/I] contribute to his success in caring for his patients[URL=http://sandiegoacupunctureandherbs.com/][/URL].
Please contact us at our [B][URL=http://sandiegoacupunctureandherbs.com]San Diego Acupuncture[/URL] [/B]Office.
Usually, people want to cognize the mastery of successful expository essay creating. Your smashing article close to this good post should be a proper basis for that people. I opine that even <a href="http://www.essayscentre.com">essayscentre.com</a> uses such information as a body for the free term papers. Thus, your writing skillfulness is very good for people.
The response level to local and national disasters is noble but it's a damn shame that so many people take advantage of the sad situations.
I mean everytime there is an earthquake, a flood, an oil spill - there's always a group of heartless people who rip off tax payers.
This is in response to reading that 4 of Oprah Winfreys "angels" got busted ripping off the system. Shame on them!
http://www.cbsnews.com/blogs/2009/08/...
[url=http://www.google.com/relief/haitiearthquake/][img]http://www.essence.com/images/mt/haiti-earthquake.jpg[/img][/url]
Hurricanes, Earthquakes and Floods belong to nature - but kindness belongs to humans.
Are you part of the problem or the solution? These people need your help!
Give assistance to adolecents!
http://www.google.com/relief/haitiear...
how r u, spring is cooming! good post there, tnx for dehora.net
[url=http://www.amnesty.org/][img]http://stores.lunaroasters.com/catalog/ChildrensLogo_WEB300.gif[/img][/url]
Helping other children of this generation promises your own children a better future.
[b]Find a Charity and Give![/b]
http://salvationarmy.org
http://www.redcross.org/
http://www.amnesty.org/
100308SLZZQA sweater in the fall and winter wear high-frequency, women north face jackets determines its protagonists in clothing. A close-fitting or to provide customized design sweater highlights mens north face jackets exquisite restaurant of the curve, created concavo-convex a warm effect. As I leave the discount men north face jackets , more and more instead of dominance of dark tones, rich, uncharted bright color: pink, powder blue, black, and so on is a favorite with young kids north face down jackets . In the build-up to the play-by-play, put on a colorful jump cheap north face women jackets sweater, as people went back to the spring. http://www.thenorthfacesaleonline.com/
100308SLHYZ
A most exciting new style ugg classic cardy for the Ugg line!Side zip on inner calf offers chanel handbags fresh style and easy on and off. Cute ugg short boots flaunts a soft suede upper and smooth seams. coach handbags Genuine sheepskin sockliner naturally wicks moisture away for dry, happy feet. Free shipping and fast delivery to your door. As a online shopping platform,ugg bailey button we have professional sales team, service team and securtiy team. We can provide fashion gucci handbags design and high quality online for our customers. http://www.officalugg.com/products_al...
[URL=http://www.dailysportscash.com][IMG]http://www.sportsbettingchamp.com/images/sbacct1.jpg[/IMG][/URL]
Hi
I've been a visitor of this discussion board for a while but didn't get around to making it official and registering!!!
A couple of days ago, I found a great thread here about methods to sportsbetting.
For some reason I can't seem to find the original discussion thread is located, but I thought to comment and say that DailySportsCash.com [url=http://www.dailysportscash.com]Betting[/URL] site is the best out of all the options mentioned. :)
http://www.onboots.com
http://www.onboots.com
http://www.onboots.com
http://www.onboots.com
http://www.onboots.com
http://www.onboots.com
http://www.onboots.com/kids-timberlan...
http://www.onboots.com/mens-timberlan...
http://www.onboots.com/mens-timberlan...
http://www.onboots.com/mens-timberlan...
http://www.onboots.com/mens-timberlan...
http://www.onboots.com/mens-timberlan...
http://www.onboots.com/mens-timberlan...
http://www.onboots.com/womens-timberl...
http://www.onboots.com/womens-timberl...
http://www.onboots.com/womens-timberl...
http://www.onboots.com/specials.html
--------------------------------------------------------------------------------------------------------------------------------
http://www.onlypuma.com
http://www.onlypuma.com/mens-puma-sf-...
http://www.onlypuma.com/mens-puma-bay...
http://www.onlypuma.com/mens-puma-dos...
http://www.onlypuma.com/mens-puma-flu...
http://www.onlypuma.com/mens-puma-fut...
http://www.onlypuma.com/mens-puma-fut...
http://www.onlypuma.com/mens-puma-fut...
http://www.onlypuma.com/mens-puma-laz...
http://www.onlypuma.com/mens-puma-sf-...
http://www.onlypuma.com/mens-puma-spe...
http://www.onlypuma.com/mens-puma-spe...
http://www.onlypuma.com/mens-puma-tri...
http://www.onlypuma.com/mens-puma-tri...
http://www.onlypuma.com/mens-speed-ca...
http://www.onlypuma.com/puma-ducati-t...
http://www.onlypuma.com/puma-kimi-rai...
http://www.onlypuma.com/womens-puma-b...
http://www.onlypuma.com/womens-puma-b...
http://www.onlypuma.com/womens-puma-d...
http://www.onlypuma.com/womens-puma-e...
http://www.onlypuma.com/womens-puma-e...
http://www.onlypuma.com/womens-puma-f...
http://www.onlypuma.com/womens-puma-f...
http://www.onlypuma.com/womens-puma-f...
http://www.onlypuma.com/womens-puma-r...
http://www.onlypuma.com/womens-puma-s...
http://www.onlypuma.com/womens-puma-s...
http://www.onlypuma.com/womens-puma-s...
Know air Jordan shoes is a brand of Nike’s. Jordan shoes, grew up together with Jordan’s fame becoming a as a famous <a href="http://www.discountjordanshoes.com/Air-Jordan-b6-1.html" title="wholesale nike shoes">wholesale nike shoes</a> brand. And Jordan led to a development of the industry. <a href="http://www.ebaykicks.com/air-jordan" title="wholesale nike shoes">wholesale nike shoes</a> 2010 series has come a long journey <a href="http://www.discountjordanshoes.com/Jordan-DMP-b66-1.html" title="jordan dmp">jordan dmp</a> before, is well known in the world!
The celebration of the Cheap Air Jordan 2010 and Jordans 25th anniversary are [url=http://www.discountjordanshoes.com/Air-Jordan-b6-1.html]wholesale nike shoes[/url] the pinnacle of a year full of [url=http://www.ebaykicks.com/air-jordan]wholesale nike shoes[/url] milestones for Michael Jordan. Consumers always want to go beyond the imagination of the future of its most daring [url=http://www.discountjordanshoes.com/Jordan-DMP-b66-1.html]jordan dmp[/url]. Although this discount air jordan 2010 shoes now may appear to be a simple one,
Know air Jordan shoes is a brand of Nike’s. Jordan shoes, grew up together with Jordan’s fame becoming a as a famous wholesale nike shoes brand. And Jordan led to a development of the industry. wholesale nike shoes 2010 series has come a long journey jordan dmp before, is well known in the world!
Water4Gas was founded in 2006 by Ozzie Freedom, who moved to the United States in 2001 after raising a family and working as a hi-tech engineer and senior technical writer in Israel. Inspired by inventors of alternative energy from around the world, Ozzie began his research into making fuel-efficient engines that could save money and the environment at the same time.
As demand grew, so did the need for this technology. With fuel prices topping an astounding $5 per gallon in the US in mid 2008, Water4Gas took their message to the media with national radio shows, TV news reports and demonstration events occurring in many cities all over the country.
As you read this page, we have grown into a massive global movement, leading the entire water-fuel industry.
The Society of Automotive Engineers (Troy, Michigan)
If you were under the impression that American automotive engineers (Detroit) are unaware of the benefits of hydrogen-on-demand, here's a wake-up pile of evidence; just a few of the many references from their official publications of the last 35 years!!! Proof that they KNOW all about it but say noting to the public:
•...increases the flame speed at all gasoline air/fuel ratios, so engine operation at very lean mixtures is possible. [July.02]
[b]Visit Our Site[/b]
Renewable Energy Company
Our Mission
To lead the Water-Fuel Movement to educate the world on vital alternatives to costly and harmful fossil fuels, while offering lucrative business opportunities and a valuable game for all to play.
[b]
green energy solution[/b]
Green Enegry News WATER4GAS.COM
[url=http://moving22.blogspot.com/]
Online Mortgage [/url]
http://pcrepairla3.blog.friendster.co...
Hi
Costume Jewellery Watches, items on auctions & discount prices on
[url=http://auxwatches.007sites.com]cie watches[/url]
[url=http://colewatches.5webs.net]citizen solar watches[/url]
[url=http://jojowatches.hostaim.com]cole watches[/url]
[url=http://watches.awardspace.biz]concord diamond watch[/url]
[url=http://watchestop.0catch.com]costume watches[/url]
Todd Cowle Municipal Bond Credit Report synthesizes, analyzes and presents aggregate credit information and trends in the municipal bond market. The report includes municipal bond rating information from the three major rating agencies – Moody’s Investor Services, Standard and Poor’s and Fitch Ratings.
Hello Everybody
Definitions for global warming are generally too scientific to participate in - but, earthquakes and mass death cannot be another disregarded statistic. Hundreds of thousads are dead and homeless
[b]Please offer financial or volunteer assistance to Chile and Haiti[/b]
http://www.google.com/relief/chileear...
Kate Moss on the catwalk for the first time in forever http://www.watchesxm.com (in a McQueen dress that Philip Green would later buy at auction for ?100,000) - http://www.uggsoutletstores.net dancing and shaking her booty so that you'd never believe she really hates it; James Corden and David Walliams camping http://www.uggs-outlet.org it up spectacularly down the catwalk and snogging at the end of it, in front of all the photographers, with tongues; http://www.shoesucn.com Naomi Campbell prancing up on the arm of Piers Morgan, giving a final flourish to their famous tabloid battle; Yasmin and Amber le Bon walking the catwalk together; http://www.donuggboots.com/UGG_Bailey... Ronnie Corbett dancing up to Michael Jackson's Billie Jean - and then dancing back down again to be met by Alexandra Burke; http://www.cheap-ugg-sale.net/ugg_583... Gavin & Stacey and Eastenders star Larry Lamb sauntering up smiling as if he does it every day; Shirley Bassey, http://www.watchesxm.com/Omega.html in glittering gold Jenny Packham, appearing to a roar from the crowd; a pregnant Denise Van Outen in floaty white Jasmine de Milo; http://www.watchesxm.com/Piaget.html The Saturdays appearing all together wearing Ungaro and Moschino; http://www.usa-coach-outlet.com Jamelia up next with her two little girls (clearly born for the spotlight, grinning shyly but very happily); http://www.watchesxm.com/Rado.html Bob Geldof and his girlfriend Jeanne Marine in the front row grinning at Pixie as she strode by in DVF.