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?
> 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?
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.
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)
On Saturday, October 6, 2012 5:13:05 PM UTC+1, Alexander Zaslonov wrote:
> 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?
On Saturday, October 6, 2012 12:13:05 PM UTC-4, Alexander Zaslonov wrote:
> 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?
On Mon, Oct 15, 2012 at 1:51 PM, Alexander Zaslonov <
zaslonov.alexan...@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:
