Social Basis (60P)
Communication is a social, rather than a purely technical problem. It requires a client and server to agree on enough points that the client can fulfil its user's needs. In REST, the client and server exist under different agencies; typically different organisations. For unconnected agencies to agree enough to communicate, we must choose our social battles. (60Q)
The goal of REST verb definition is to close the verb battlefield, and move the fight into the remaining content type and noun spaces. The verb battle can fought on purely generic technical issues, thus we use as few verbs and as few interpretations of those verbs as possible to achieve maximum generic theoretical expressiveness. (60R)
Other verbs may be useful to perform special protocol-level functions: It may be useful to request the OPTIONS of a web server, or to use TRACE. However, this page is dedicated to describing the minimum state transfer operations. (5YH)
Verb Selection (60S)
Fielding does not list the proper methods to use in a RESTful architecture. Instead, he simply says the should be standard. As a contributor to today's HTTP specifications, we can see a probable bias towards those defined in the spec. We can also infer from his "state transfer" terminology that he wants to separate the meanings of state (content) and the transfer operations. This yields a minimal set of methods that can be used for any resource, allowing for variation of content types and schema between resources. (5ZN)
The minimum methods we will describe are GET, PUT, POST, and DELETE. They correspond roughly to the CRUD verbs READ, UPDATE, CREATE, and DELETE but more closely to the cut-and-paste verbs COPY, PASTE OVER, PASTE AFTER, and CUT. (5YI)
All communication can be modelled as simply transfer of state (information) from one software component to another. These minimum methods are designed to cleanly separate the state being transferred from the verbs being used in the transfer. The transferred state moves to the content-type space. (60T)
GET (5YJ)
GET is the HTTP equivalent of COPY. It transfers a representation from resource to client: (5YK)
(C) <- (R) (5YL)
The schema of the content must contain enough information for the client to usefully operate on the data. It will often include links to other resources as well as structured or semi-structured data. All possible read-only information gathering can use the GET method: State is transferred from a named resource to the client whenever the client needs the current state. (5YM)
GET may be replaced in some environments by a subscription model. This is likely to be required where the percieved value of old data quickly degrades as new data arrives to replace it. Under these circumstances a client-initiated GET may result in rapid polling, and the extra server-side state associated with subscription may be worthwhile. (5YN)
Theoretically, GET could be enough for all state transfer operations. A server object could reach back to a client resource to support two-way state transfer. The main limitation of this is that a server typically does not know when to issue a GET request, or to whom. In REST we do see a distinction between client and resource, rather than viewing them as peers. Where there is asymmetry in our model of client and server, there must be an additional method to reflect it. (5YO)
PUT (5YP)
PUT is the HTTP equivalent of PASTE OVER. It is the exact opposite of GET. It transfers state from a client to a resource: (5YQ)
(C) -> (R) (5YR)
The same content type is like to be used in your PUT as you would have seen returend from your GET. The schema must again contain enough information, this time for the resource to operate on the data. If you think of your resource as an object, the schema must contain enough information to fill out all of the object's member variables. The schema may not be in exactly the same form as the object's member variables, for example a circle could be defined as either a (centre-point, radius) pair or as any three points along the circle's circumference. (5YS)
Theoretically, GET and PUT are sufficient for all state transfer operations. We have addressed the asymmetry problem by allowing clients to initiate a state transfer to the server. So we are done, right? (5YT)
Well, GET and PUT are fine for transferring the state of existing resources. PUT can even implicitly create new resources, either by storing to a url that returned "404 Not Found" before the request and now returns "200 OK", or by storing to a collection resource such as a list. New list entries can be created by PUTting a list that contains the current set of entries, plus an additional entry. That may even create an independent resource for the new entry. (5YU)
The more you get into lists and queues, however, the more limited the PUT request seems. It is easy to accidentally paste over someone else's recent change with your own when you have to PUT the state of the whole list resource each time. It would be nice to be able to deal with resource creation and destruction in a more elegant way. (5YV)
POST (5YW)
POST is our PASTE AFTER verb. It says "Don't overwrite what you currently have: Add to it.". This can have a couple of alternative effects: (5YX)
Create a resource (201 response) (5YY)
The most obvious direction from our current line of reason is resource creation: (5YZ)
(C) -> (R) -> (R) (5Z0)
A client sends a POST request to a resource. The request contains a representation of a resource that doesn't exist, yet. That resource is created, and its url returned to the client in the Location header. (5Z1)
Some of the state of the request resource tends to be transferred to the created resource. If you post a new entry to a list, it tends to become that list's child rather than the child of another list. The request resource can be seen as a factory which combines its own state with the state in the request body during resource creation. (5Z2)
Add to a resource (200, or 204 response) (5Z3)
POST might not actually create a new identifiable resource. It may append to the existing resource in a safe way. (5Z4)
(C) ->> (R) (5Z5)
A client sends a POST request to the resource, with a representation of the additional state being transferred. (5Z6)
DELETE (5ZC)
DELETE is the HTTP equivalent of CUT, although it usually doesn't transfer a representation of the final state of the resource before destruction: (5ZD)
(C) -> xxRxx (5ZE)
(It is also the most difficult to repesent in simple ascii art. Just picture the Resource bubble being crossed out) (5ZF)
DELETE is the counterpart of POST's resource creation semantic. It requests the resource state be destroyed, or at least removed from the public web. (5ZG)
Conclusion (5ZL)
It can be tempting to push custom method invocations through a HTTP POST request, like SOAP does. It can be tempting to think that your body is a list of parameters to a function call. (5ZH)
These actions are tunnelling. (5ZI)
REST is about minimising the number of battle-grounds you need to fight your political battles on. Verb selection is not one you need to fight on an individual basis. These methods should be all you need to build even complex software when used with content types that cover the schema of the resources are you define. Circumventing this model makes it difficult to implement intermediataries of all kinds, from caches to security policy layers. It also moves the social question of protocol design back into the verb space. (5ZJ)
REST says "no". Fight your battle in the content-type space. Use standard identifiers, a standard resource abstraction layer, standard meanings for your standard verbs, and fight your social battles in the content-type space. The other battles have already been won, so when you win battle number four you have won the war. See WhichContentType and BenjaminsRESTTutorial for more information. (5ZK)