“If you find yourself in need of a distributed transaction protocol, then how can you possibly say that your architecture is based on REST? I simply cannot see how you can get from one situation (of using RESTful application state on the client and hypermedia to determine all state transitions) to the next situation of needing distributed agreement of transaction semantics wherein the client has to tell the server how to manage its own resources.”

— Roy Fielding, rest-discuss, 2009-06-09

Is it just simply revising what the HTTP methods were designed for and how they behave on browsers/servers/caches/proxies?

It's not that long. I have yet to see a paragraph-length description that is an accurate summary of it (and blog-entry-length descriptions cause a lot of confusion).

REST is, of course, modeled on the Web, which uses (X)HTML for its resources and HTTP as a transport. Web pages do not come with a separate document describing where forms should be submitted to or where a particular page is located -- this information is contained within the page itself.

The problem is that this is completely opposed to the "standard" RPC model, in which the URLs and methods to use are specified by an external document. Further complicating the use of REST is that many developers (such as the author of the article) are using second- or third-hand knowledge of what REST is and how to implement it. This sort of cargo-cult mentality leads to bizarre concepts such as a "RESTful URL".

REST is somewhat vague -- the phrase "like how the web works now" doesn't contain enough information to properly implement. For this reason, one popular way to describe it is in terms of what it is not. After eliminating the protocol models which are not REST, what is left is REST.

For example, one popular RPC model is to POST documents describing actions to a well-known URL, such as "/rpc/call". A possible exchange:

    POST /rpc/call
    <method name="get-time"/>

    200 <result status="ok"><time>2009-05-06T07:08:09Z</time></result>

    POST /rpc/call
    <method name="set-time"><time>2009-10-11T07:08:09Z</time></method>

    200 <result status="no-such-method"/>

Many people looked at that and said: "this is silly! nothing is properly cached, and we can't re-use existing HTTP libraries for error handling". This the advent of (typically ad-hoc) RPC protocols over HTTP. This seems to be the most popular model for web applications, currently. An example of such a protocol is the Twitter API: every method is described in an external document, and client applications hard-code the URLs to various method names. These RPC-over-HTTP protocols are sometimes called "REST", due in large part to the cargo-cult mentality mentioned earlier, but do not provide any of the benefits of a true REST API.

A third category I'll call pseudo-REST, because apps designed to use it are based on REST with a few exceptions (typically authentication). Many web applications (ironically, News.YC isn't) are pseudo-REST -- for example, to add a comment, there might be the following form:

    <form method="post" action="/new-comment">
    <input type="text" name="name"/>
    <textarea name="text" rows="8" cols="80"/>
    </form>

Finally, we get to a REST protocol. These are just like pseudo-REST, except that the user is authenticated on every request rather than just once. A "fully" RESTful protocol is typically seen in APIs.

Trying to perform guaranteed updates across HTTP transactions is always going to be tricky. The other factor is old database principals atomicity and ACID.

1. Put a uuid under /transactions/

2. /transactions/<uuid>/ is a COW copy of /

3. make changes

4. put "commit" to /transactions/<uuid>/status