What’s the best RESTful method to return total number of items in an object?
I’m developing a REST API service for a large social networking website I’m involved in. So far, it’s working great. I can issue GET, POST, PUT and DELETE requests to object URLs and affect my data. However, this data is paged (limited to 30 results at a time).
However, what would be the best RESTful way to get the total number of say, members, via my API?
Currently, I issue requests to a URL structure like the following:
- /api/members—Returns a list of members (30 at a time as mentioned above)
- /api/members/1—Affects a single member, depending on request method used
My question is: how would I then use a similar URL structure to get the total number of members in my application? Obviously requesting just the id field (similar to Facebook’s Graph API) and counting the results would be ineffective given only a slice of 30 results would only be returned.
Answer
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 - https://api.stackexchange.com/docs/users