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