Open Stack

Aloha guardians of the API!

I haven recently* reviewed a spec for neutron [1] proposing a distinct URI
for returning resource count on list operations.
This proposal is for selected neutron resources, but I believe the topic is
general enough to require a guideline for the API working group. Your
advice is therefore extremely valuable.

In a nutshell the proposal is to retrieve resource count in the following
way:
GET /<prefix>/<resource_name>/count

In my limited experience with RESTful APIs, I've never encountered one that
does counting in this way. This obviously does not mean it's a bad idea.
I think it's not great from a usability perspective to require two distinct
URIs to fetch the first page and then the total number of elements. I
reckon the first response page for a list operation might include also the
total count. For example:

{'resources': [{meh}, {meh}, {meh_again}],
 'resource_count': 55
 <link_to_next_page>}

I am however completely open to consider other alternatives.
What is your opinion on this matter?

Regards,
Salvatore


* it's been 10 days now

[1] https://review.openstack.org/#/c/102199/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20141120/36dd1605/attachment.html>