Rather than depending on an external document for the protocol semantics, depend on standard transport semantics and information embedded in data returned from

Rather than depending on an external document for the protocol semantics, depend on standard transport semantics and information embedded in data returned from the server. 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"/> Notice that HTTP is not relevant at all to this exchange -- the URL is always the same, the status code is always the same (200, success) and the details of the exchange are contained entirely in the request bodies. This is the model used by protocol frameworks like SOAP. 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> In REST terms, this describes the HTTP method, URL, and expected parameters of a request to create a new comment. Almost all information needed for a successful request is contained within the page itself. The "almost" is why this is "pseudo" REST -- web applications typically use cookie-based authentication, because the user experience is much improved over HTTP auth. 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.