Should you have used POST in the last two repetitions of this code?
Gaius G.

Frankly, I am more concerned about impact of REST on usability these days because some of the extensive REST API’s I’ve seen, like SoundCloud’s, made my eyes rollback like the way sound engineers’ desk do: whole lot of knobs, buttons, and sliders that all look alike. They screamed of beauty and order yet radiated total indifference to common needs.

Your XML example of a country code doesn’t actually contain any URLs, so the application needs to know how to construct them. Why not just include the URL in the XML? After all, this is how it’s done in HTML and ATOM. This way the application doesn’t need to know how to construct urls, only how to follow links. The application still needs to know enough about the resource representations to know where the links are, but it doesn’t need to know how to construct links according to your (possibly changing) scheme.

We can take this further and have the state representation include links and methods for all operations that can be done on the resource and related resources. In your country example, there could be a link “up” to a page that lists all country urls, a notation that you can PUT to the present resource to replace it, and POST to another url to create. Again, browsing web pages is a good human analogy: nav bars, breadcrumbs, etc, are all to facilitate browsing. Just do for machine browsers what you would have done for a human browser. (The result will probably end up looking more like gopher, if you remember that.)

The problem is there’s no standard “language” (other than maybe html A, LINK, and FORM elements) for expressing these relationships, so every representation has to roll its own and every application has to understand that particular representation’s way of linking to resources.

Also, this only gets you to the point where an application can POST for create, and then, after the application knows the URL, it can PUT for updates. Maybe it will always be too much of a burden to require PUT for create.

Web Application Description Language (WADL) is trying to address this space for RESTful apis in the same way that WSDL tried to do for more RPC-like protocols. I definitely think there’s a place for things like this (and it may have mechanisms to enable reliable “PUT-create” operations), but solutions like this are heavy and still don’t put the resource links *inside* the representation itself.

http://wiki.openstreetmap.org/wiki/Talk:API_v0.6#Overloading_of_PUT_method

—-

Kurt Cagel: “Yet if you assume idempotency (and hence non-destructive PUTs and revisional content)…”

I think you misunderstand the word “idempotency”. From http://en.wikipedia.org/wiki/Idempotence

“Idempotence (…) is the property of certain operations in mathematics and computer science, that they can be applied multiple times without changing the result beyond the initial application.”

PUT can be destructive yet idempotent. The point is that if you do the PUT two or more times it has the same effect as only doing it once. If a system creates new revisions (and mints new revision URIs) for each PUT operation even if the representation put is the same then the operation is not idempotent. If it simply overwrites the resource with the given URI then it may well be.

The distinction actually is more subtle. Assume for the moment that you know nothing about the back end state or representation of the object in question – that is to say, there is a transformation that converts your POSTed or PUT document into the internal state of the server. If you assume that you have a purely idempotent system (one where a resource is never destroyed) then PUT becomes a mechanism for handling versioning. I’ve actually been working on such a system for a publishing client, in which POST effectively creates a new “resource” while PUT updates that resource, but in the back end, the POST actually creates two “documents” – a resource “proxy” and the first or base revision of that document. The PUT, on the other hand, will just create a revision of that original document and save it, with the revision having a different identifier than that version version of that document.

When you retrieve that document, you are getting the latest revision of that document, but the system itself never destroys previous revisions. What’s more, the same system can store within each revision its revision chain (via URL pointers stored in an envelope holding the document), meaning that the base object will have an auditable history. This implies that in such an environment, even PUT is non-destructive.

The processing pipelines in this case are really the key to this. A lot of (perhaps most) people have some strong misconceptions about REST. The first is that if you use GET and POST, you are engaging in REST, yet the vast majority of such calls are in fact RPCs (especially POST) – you are passing a bundle of parametric content along with an imperative expressed through either the URL or the payload, and you get back other content as a consequence.

The second expression of REST is that it is in fact nothing but CRUD, that you save or load resources to a database through a URI. While this is technically more RESTful, it does not take advantage of the fact that the internal and external representations of a resource do not necessarily have to match – so long as the external representation can be transformed from an internal representation and vice versa (albeit with no requirements that the results coming in or going out have to be the same representations) you are still doing RESTful operations.

Yet if you assume idempotency (and hence non-destructive PUTs and revisional content) then what emerges is a truly “stateless”, purely declarative system, because you can, in theory, pass in a time parameter and get back the state of that resource at that time for any time in a resource’s history.

This has profound implications for semantic systems. One of the biggest challenges that linked data systems face is that in a destructive REStful system, RDF triples can only describe relationships relative to the current state of the triple store system – even if such triples are themselves never destroyed. On the other hand, in an IDEMPOTENT PUT system, the relationships that resources have (assuming that the predicate of such a relationship is also defined in such a manner) can be rolled forward or back over time. As a consequence, such a triple store becomes a time machine that evinces the relational descriptions between its resources based upon the timestamp of the query.

I’m aware that there are data modeling systems that do this already, but I think as the relationships between resources, REST and RDF become more fully understood (and I do believe there is a DEEP connection between these) and as hardware and software systems advance to the point where idempotent PUT becomes the norm rather than the exception, I believe that we’ll see some very interesting developments in this space.