What is the REST interface?

REST means that URLs mean something.

REST can mean that every possible state has a specific URL. It follows then that most websites are not RESTful, since most have state that varies at a given URL. For instance, a lot of sites ask users to login. Only a site made of static documents is truly RESTful (or a site that imitates static documents).

What else can REST mean? Some people associate with verbs: GET, POST, PUT, DELETE.

What is the model? Mark Baker offers this:

The model of how stuff happens with REST’s generic interface is based on resources (or objects, if you like), and containers. Of course, containers are themselves resources, ala CompositePattern. Now, each resource has a type associated with it. It’s a late-bound (aka dynamically bound) type of course, meaning that the type is orthogonal to the interface, or in other words that you discover the type after you access the resource. With REST, this is done with a GET (or conceivably a HEAD if you use the Resource-Type header).

Containers are, like their name suggests, resources which “accept things into them” if you like, the way that “add” works with Glasgow Beans, or “write” works with JavaSpaces. The resource-centric view of them suggests that their state is usually some function of all the things that they have accepted into them since their initialization. So for example, the current state of a mailing list archive is a function of its initial state (some banner describing the list) and the set of all messages which have been sent to the list.

Containers can do all sorts of interesting things, as you might imagine. The state of the container can change in completely arbitrary ways depending upon the information they’re asked to contain, plus any other information they feel is relevant (current time, phase of the moon, etc..). In addition, the form of interface that they present can be quite rich; certainly the HTTP interface is, with features such as the 201 response code for signalling the creation of new resources subordinate to the container.

Bringing this all back to PUT/POST, hopefully it should be clear that PUT’s job is to set the state of some resource explicitly, and that it does this to the exclusion of any existing state that might be there, i.e. you can’t use it to do an incremental update of a single resource. It also holds for containers. If you PUT to a container, you are attempting to overwrite the state that was constructed from all the previous POSTs to it. So to reuse the mailing list example, if you PUT to the mailing list, you’ll be overwriting the index of the archived messages (since the messages themselves have their own identity).

POST’s job is simply to logically add something to a container.

Another not-so-obvious thing about PUT vs. POST is that for PUT, since you’re trying to replace the state of some existing resource, you have to know the URI of the thing that you’re replacing. With POST, you send data to a container, and if it’s the right type it will create a new resource and tell you about it with a 201 response. When you also factor in that URIs should be opaque, and clients shouldn’t typically be constructing them unless they’re following orders (like a GET form) or the authority doing the PUT happens to also run the server, a rule of thumb falls out; if you want to create a resource, POST a representation of its state to a container that will assign it a URI.