Roy Fielding writes:
“REST is an architectural style that, when followed, allows components to carry out their functions in a way that maximizes the most important architectural properties of a multi-organizational, network-based information system. In particular, it maximizes the growth of identified information within that system, which increases the utility of the system as a whole.”

http://roy.gbiv.com/untangled/2008/on-software-architecture

Here’s how I apply this to your example. You already decided that you don’t want to make the list of 200 books into a piece of “identified information”. This list exists only on the client. So, there is no benefit in applying the REST architectural style to this part of the overall “information system about books” problem.

It’s great that a book is individually addressable for CRUD operations (that is, each book has become “identified information”).

But, unless the list of 200 books that the client is interested in becomes a piece of identified information, this part of the system is just part of the client, not part of the web. So, if the regular REST API of the server is insufficient for the client, because it is too inefficient for your overall design, it makes sense to have a specific operation between client and server to support this feature of the client. Nothing has been lost by having the operation fall outside of the REST architectural style, because the information it is the “subject” of the interaction is not identified information on the web.

It breaks some RESTful principles (proxying, most notably), but each MIME part amounts to a separate HTTP request that can be replayed into the same handlers that would be triggered by that request when submitted “normally.”

It’s also nice since you don’t need to keep a cross-request transaction open when you want to make multiple updates transactionally.

To be honest, I think a big POST is fine in your example, since at the time your first request is made the server has no concept at all of the local “resource”. Afterwards though, there’s nothing then preventing the server from maintaining a version of the of it as an identifiable resource on the web that could support further interaction.

What you describe is the same I mentioned in the blog post I guess:

I can imagine some workarounds for this, like saving a temporary list of books with PUT, and then doing the query on that temporary list’s URI

I probably wasn’t clear, since that was brought up by Leonardo too.

You certainly can, but that’s what’s referred to as the RPC-style, because you’re doing a remote call to the final web server and expecting an answer to your specific query which has to be computed.

Well RPC style primarily differentiates itself by a profusion of verbs – thats not what we are seeing here. If variable optional arguments is RPC style then any pagination implementation that is otherwise ReSTful should be treated as RPC style. So I would not jump so far as to say it is RPC style. However I would admit that that was not the most satisfactory solution (which is why I went ahead with offering two more refinements on the same).

All of the RESTful properties are gone in this case, because there’s no layering, caching, etc.

If you review the final solution I suggested you will find that all the ReSTful properties are still available. You are responding to only the intermediate solution I discuss in a conversational style.

And yes, I did review the book and the resources referred to, many times over In fact while not on the same specific issue, I did offer a whole bunch of opinions on ReST here http://blog.dhananjaynene.com/2009/06/musings-on-rest/ and here : http://blog.dhananjaynene.com/2009/07/presentation-rest-explained/

If thats kosher for ReST would it be OK to pass the parameters as a part of POST instead of GET ?

You certainly can, but that’s what’s referred to as the RPC-style, because you’re doing a remote call to the final web server and expecting an answer to your specific query which has to be computed. All of the RESTful properties are gone in this case, because there’s no layering, caching, etc.

Please check out the book or some of the resources Leonardo Boiko suggested above for a more in-depth description of the reasoning behind the REST-style.

It is not unacceptable to have optional scoping parameters being passed as a part of the URL (eg. for pagination). If thats kosher for ReST would it be OK to pass the parameters as a part of POST instead of GET ?

Now maybe that breaks the URI notion of ReST. But what if I remodeled the functionality differently (I’m just thinking aloud). What if I PUT a “Query” resource and the response is a List of Books feed ? Is that acceptable ? Maybe and maybe not. Let us go with the latter. Now, I can PUT a Query resource which has a list of older URIs – the response returns me a QueryID. Note that the Query is not a typical query but is a collection of URIs. Could I now do a GET on a BookSet resource using that QueryID ? Perhaps. I could even extend it further by allowing to append more URIs by doing a POST using the earlier obtained QueryID. (Note that the QueryID could interchangeably be also referred to as a BookSetID – just depends upon which way one wants to view it). Now one gets good batching as well.

That seems to work for me.

Cheers.

It’s an interesting idea, but it’s not clear to me how that would help with the issue above, perhaps due to my lack of understanding of what URI templates will bring in addition to the templating itself.

Dhananjay,

It is a possibility, but one of the issues with this approach is that there are arbitrary and not-well established limits to how long a URI can be. There’s even an error code (413) which is used when the URI is too long.

I guess a possibility would be to ensure clients implement proper batching of the requests, on a trial and error basis. Not so great, but could work.

Update: hmm.. on a second thought, I fail to see how that would be an advantage over usual RPC over HTTP. The arbitrary way in which URIs would be built would kill most of the benefits of REST-styled architectures.