Open Stack

On 11/20/2014 08:47 AM, Salvatore Orlando wrote:
> Aloha guardians of the API!

LOL :)

> 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>}

This is (almost) what I would suggest as well. Instead of 
<link_to_next_page>, I would use a _links object per JSON+HAL (see [2] 
for an ongoing discussion about this exact thing).

The rationale for my opinion is that a URI like GET 
/$collection_name/count seems to indicate that "count" is a subresource 
of $collection_name. But count is not a subresource, but rather an 
attribute of $collection_name itself. Therefore, it more naturally 
belongs in the returned document of GET /$collection_name.

I could also support something like:

GET /$collection_name?include_count=1

that would use a query parameter to trigger whether to include the 
somewhat expensive operation to return the total count of records that 
would be returned without any limit due to pagination.

Note that this is the same reason why I despise the:

GET /$collection_name/detail

stuff in the Nova API. "detail" is not a subresource. It's simply a 
trigger to show more detailed information in the response of GET 
/$collection_name, and therefore should be either a query parameter 
(e.g. ?detailed=1) or should not exist at all.

Best,
-jay

[2] 
https://review.openstack.org/#/c/133660/7/guidelines/representation_structure.rst

> 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/
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>