ansaurus

Question

What's the best RESTful method to return total number of items in an object?

Answer 1

+1 A:

What about a new end point > /api/members/count which just calls Members.Count() and returns the result

Steve Woods 2010-09-15 08:45:20

Cheers. Think I'll go with this new endpoint approach.

Martin Bean 2010-09-15 09:50:13

Giving the count an explicit endpoint makes it a standalone addressable resource. It will work, but will raise interesting questions for anybody new to your API - Is the count of the collection members a separate resource from the collection? Can I update it with a PUT request? Does it exist for an empty collection or only if there are items in it? If the `members` collection can be created by a POST request to `/api`, will `/api/members/count` be created as a side effect as well, or do I have to do an explicit POST request to create it before requesting it? :-)

Franci Penov 2010-09-15 20:21:58

Answer 2

A:

Seems easiest to just add a

GET
/api/members/count

and return the total count of members

willcodejavaforfood 2010-09-15 08:46:15

Answer 3

+5 A:

While the response to /API/users is paged and returns only 30, records, there's nothing preventing you from including in the response also the total number of records, and other relevant info, like the page size, the page number/offset, etc.

The StackOverflow API is a good example of that same design. Here's the documentation for the Users method - http://api.stackoverflow.com/1.0/help/method?method=users

Franci Penov 2010-09-15 08:48:32

Good idea. Every list returned should specify the total count as well. Otherwise, how would you know if there was a need to fetch the next page?

bzlm 2010-09-15 08:53:44

+1: Definitely the most RESTful thing to do if fetch limits are going to be imposed at all.

Donal Fellows 2010-09-15 09:06:34

@bzim You would know there is a next page to fetch because there is a link with rel="next".

Darrel Miller 2010-09-15 11:00:55

@Darrel: Which in turn requires that the receiving code understand the word “next”. ;-)

Donal Fellows 2010-09-15 12:21:40

@Darrel Miller - `<link rel="next">` would work only for HTML payloads. if the resource is represented in application/json, that won't work.

Franci Penov 2010-09-15 20:14:00

@Franci Well it could work for pretty much an xml based media type. And it doesn't take a lot of imagination to figure out a way to encode links into JSON. Plenty of people are doing it.

Darrel Miller 2010-09-15 23:47:38

@Donal the "next" rel is registered with IANA http://www.iana.org/assignments/link-relations/link-relations.txt

Darrel Miller 2010-09-15 23:48:50

@Darrel - yes, it could be done with any type of "next" flag in the payload. I just feel that having the total count of the collection items in the response is valuable by itself and works as a "next" flag just the same.

Franci Penov 2010-09-16 00:53:53

Answer 4

A:

You could return the count as a custom HTTP header in response to a HEAD request. This way, if a client only wants the count, you don't need to return the actual list, and there's no need for an additional URL.

(Or, if you're in a controlled environment from endpoint to endpoint, you could use a custom HTTP verb such as COUNT.)

bzlm 2010-09-15 08:57:07

“Custom HTTP header”? That would come under the heading of being somewhat surprising, which in turn is contrary to what I think a RESTful API should be. Ultimately, it should be unsurprising.

Donal Fellows 2010-09-15 09:05:22

@Donal I know. But all the good answers were already taken. :(

bzlm 2010-09-15 09:07:21

@bzlm: I know too, but sometimes you've just got to let other people do the answering. Or make your contribution better in other ways, such as a detailed explanation of why it should be done the best way rather than others.

Donal Fellows 2010-09-15 12:20:18

ansaurus

tags:

views:

answers:

What's the best RESTful method to return total number of items in an object?

related questions