4. Four CRUD operations are insufficient for even modestly complex applications. Many REST-like api's include the type of operation to perform in the request, but this is against the rigid structure of the REST interface.
If someone more schooled in web design wouldn't mind answering, what problems arise of by using the GET add-contact api as described in the post? What is the benefit of using xml in the body of a PUT or POST verb vs the headers?
...the convention has been established that the GET and HEAD methods SHOULD NOT have the significance of taking an action other than retrieval.
Why? GET should mean simply getting the page. Not doing so runs the risk of:
- Bookmarks breaking (what if someone bookmarks the add-contact link?)
- Google deleting everything because it followed the links (there is an example of this on The Daily WTF)
- Easy cross-site request forgery attacks (I post an "image" with the url that deletes your address book on some message board. You are still logged in with a cookie, so it goes ahead)
Even if the site in question is doing something to prevent the above, why reinvent the wheel and not just use POST (or a more RESTful method)?
As for XML, lots of people hate it, and there is no real requirement to use it (unless your users want it, of course). JSON or even form data can work.
As for headers, there might be a risk of a stupid proxy server mangling them, but nothing should mess with the body of the request. And it's just more conventional to describe the request as the request body, and have headers act as the meta-information about it. (I'm assuming you meant HTTP headers)
In the example, the add-contact URI was dynamically generated so the deletion from following a url and and bookmark breaking did not seem especially pertinent.
But your explanation made a lot of points clear. One maintains the integrity of the call by placing parameters in the body. Avoiding proxy and caching issues inherit in using GET, as well as avoiding xss, makes immediate sense.
There can be workarounds, but using something that's not broken in the first place is better. Every one of those issues comes from other software expecting the spec (RFC) to be followed where it's not.
Another thing I remembered after I posted. There is no universally agreed upon maximum query string length, so passing parameters in GET is web server dependent.
I agree with the other reasons posted. One more reason is one of expressiveness. When you have a "flat" simple form, it is easy to serialize as name/value pairs and send to the server in that fashion. However, when a form is more complex, with nested structure or with variable-length lists of data, it can be very difficult to come up with a serialization scheme that fits the name/value pair model. Often you end up creating your own mini language. If, however, you use a JSON object or XML node as your payload, you are free to transmit data of arbitrary complexity rather easily. So in cases where the data you want to POST/PUT is not flat, you will have much more expressive power encoding your data in JSON or XML and posting it in the request body.
It fakes the PUT to help out browsers. If you pass in a _method paramater it overrides the actual HTTP verb, but this is actually done in middleware above Rails, the controller sees it as PUT.
That's giving Rails too much credit. I would say the friction of configuring Apache to handle PUT, the lack of support on shared hosting to do this, and the scarcity of PHP tutorials/interest on the subject is more contributory to half-REST implentations.
I myself have been guilty of this. At the end of the day, supporting PUT at expense to ease of use by the API consumer (and effort expended to support their toolchains and SDKs, most of which need extra twiddling to do PUT and DELETE) is just not preferable to getting something working... REST philosophies be damned.
What kind of configuration do you need to do to 'enable' PUT and DELETE? In my experience with 1.3, 2.0 and 2.2 it was always proxied correctly. I am using primarily nginx these days which also proxies the HTTP method without any special configuration.
If you're using mod_php, you have to configure a script handler for PUT requests, and then read from stdin in PHP instead of using the superglobals. Is it hard? Not really, but it's not as easy as using $_POST. Here's a tutorial for anybody interested:
1) Use the ad-hoc standard of a form parameter "_method=PUT|DELETE".
2) Read the "Content-Type" header of the request to find out how to parse it. Whats so hard about that?
REST is where Javascript was 8 years ago, everybody things its horrible because very few people actually understand how the whole thing works, and all the implications of that.
