URL for total count of items in a resource

[Alexander Zaslonov]

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?

[Bill Walton]

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

[Kristof Kotai]

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

[Alexander Zaslonov]

Thank you guys, it seems there are still no common practices for that.

[Dean Landolt]

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.