States vs. Operations
- Yesterday, in a meeting at JBoss, I was evangelizing REST to a few of my
colleagues. An interesting question came up:
Let's say you have a distributed cache you want to manage through a
RESTful interface. One operation on the cache is clearing or flushing
it. The interesting thing about flushing is that the act of flushing
changes the state of the cache, but "flushing" isn't a state of the
cache itself. It seems to be a pure operation. How do you model
something like this in REST? Is it correct to do:
PUT /cache/flusher (PUT because flushing is idempotent)
Or maybe even better:
returns a document like
<link rel="FLUSH" href="/cache/flusher"/>
Or maybe this is better:
Maybe I just answered my own question :)
Thanks for listening,
JBoss, a division of Red Hat
- Sam:I think I didn't explain myself properly.I cases like this (clearing a cache, queue, work-list, etc.) when I would like the server to not only clear the list, but also create an auditable record of the action (something beyond standard HTTP server logs), I tend to use POST as this results in the work being performed (clearing the list) and the creating of a new resources (the auditable record). POST also helps when I expect the client to be able to send some state information that would affect the task at hand (filter for items to remove from the list, etc.). The POST returns 201 Created w/ a Location header as expected.To go a bit further along this line, In cases where I don't need an auditable record, but still want to support sending state, I usually use a PUT against a known resource. This may result in a GET-able resource that shows details on the last action committed, too.Finally, when I don't need a record of the action and I don't expect the client to send any state along at all, DELETE against the worklist resource works for me.mcahttp://amundsen.com/blog/
On Mon, Jun 29, 2009 at 14:52, Sam Johnston <samj@...> wrote:On Mon, Jun 29, 2009 at 7:16 PM, mike amundsen <mamund@...> wrote:Well PUT shouldn't really be doing any (well, much) work anyway so there's no need for logs and so on.
I find POST is very handy in cases like this when, in addition to handling the request for work, I also want an audit log of the request along with the final result of the request. In those cases, I define a representation that contains the details of the state request that the client can send to the server. When the work is done, the results are stored as a unique resource in an archive that can be used for searching, reporting, etc.
Returning multiple resources (e.g. the byproduct(s), logs, etc.) when there's only one Location: header is an interesting problem, but one that could likely be solved with HTTP Link: headers.