On 11/20/2014 09:12 AM, Jay Pipes wrote:
> 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

It feels like the right thing is a standard 'more' definition included
in the next link:

{'resources': [{meh}, {meh}, {meh_again}],
 'next': {link: ...., total: somebignumber}}

Or the way gerrit does it:

shared storage checks for live migration","owner":{"name":"Jonathan
shared storage checks for live migration\n\nDue to an assumption that
libvirt live migrations work only when both\ninstance path and disk data
is shared between source and destination\nhosts (e.g. libvirt instances
directory is on NFS), instance disks are\nremoved from shared storage
when instance path is not shared (e.g. Ceph\nRBD backend is
enabled).\n\nDistinguish cases that require shared instance drive and
shared libvirt\ninstance directory. Reflect the fact that RBD backed
instances have\nshared instance drive (and no shared libvirt instance
directory) in the\nrelevant conditionals.\n\nUpgradeImpact: Live
migrations from or to a compute host running a\nversion of Nova
pre-dating this commit are disabled in order to\neliminate possibility
of data loss. Upgrade Nova on both the source and\nthe target node
before attempting a live migration.\n\nCloses-bug: 1250751\nCloses-bug:
1314526\nCo-authored-by: Ryan Moe
\u003cr...@mirantis.com\u003e\nCo-authored-by: Yaguang Tang
\u003cyaguang.t...@canonical.com\u003e\nSigned-off-by: Dmitry Borodaenko
I2755c59b4db736151000dae351fd776d3c15ca39\n(cherry picked from commit
update for German","owner":{"name":"Thomas
update for German\n\nThis patch has been sent to the Debian bug tracker,
and I am\nnow forwarding it upstream.\n\nChange-Id:

Basically a tail record that would tell you some additionally useful
information about the query, that includes rows returned, timing, next
link, and estimated total rows (knowing that's not possible to be accurate)

> 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

Sean Dague

OpenStack-dev mailing list

Reply via email to