URL for total count of items in a resource

Showing 1-5 of 5 messages
URL for total count of items in a resource Alexander Zaslonov 10/6/12 9:13 AM
Dear all,

Recently I designed an interface for API and run into dilemma of how to define URL for total count of items in a resource. Having done some research I found a couple approaches for that:

1. Define a URL like /service/resource/count.

2. Return the total count in the header, so that it's possible to get it using HEAD method without loading the resource itself.


Could you please comment on these approaches or propose any other?
Re: [api-craft] URL for total count of items in a resource Bill Walton 10/6/12 11:51 AM
Hi Alexander,


I'm currently in the midst of a similar project.  I'm developing in Rails and neither of those options was an obvious fit.  What I ended up doing is defining a couple of query parameters to signal the need for counts and sums:  computed and computation_type.  computed can be true or false.  computation_type can be count or sum.  So to retrieve a count of active clients, for example, the URL is: /clients?computed=true&computation_type=count&client_status=active.  I'm not altogether happy with it, but it makes it easy on the controller and easy to understand inasmuch as the same query without the two parameters retrieves the actual data elements.

HTH,
Bill
Re: URL for total count of items in a resource Kristof Kotai 10/7/12 5:16 AM
When using HEAD, you should be returning exactly the same response as if GET was used, except for the response body.

That means if you go with this approach, you should be including the "count" in the headerlist also when GET is used. 

GET   /books
HEAD  /books

Not sure how much overhead does that add to the execution time on the server, if not much, then use that. Otherwise, create a separate URI like the one in 1.

GET   /books/count

(I would rather use something more general though, so later you could add something else here too
GET   /books/meta)

Cheers
Re: URL for total count of items in a resource Alexander Zaslonov 10/15/12 10:51 AM
Thank you guys, it seems there are still no common practices for that.
Re: [api-craft] Re: URL for total count of items in a resource Dean Landolt 10/15/12 4:14 PM


On Mon, Oct 15, 2012 at 1:51 PM, Alexander Zaslonov <zaslonov....@gmail.com> wrote:
Thank you guys, it seems there are still no common practices for that.

Check out the Range header -- it's the best kept secret of http. It's not just for bytes -- you can define your own range type. For instance dojo defines an "items" range for paginating in its JsonRestStore. The semantics of the range header gives you a consistent way to treat resources as collections and as an added bonus it gives you a nice clean way to slice or paginate any of your collections. But it also gives you a good way to optionally provide a total count with any request:

GET /books
Accept-Ranges: items

200 OK
Content-Range: items 0-10/10


And of course this works fine for HEAD requests.