Open Stack

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:

...
{"project":"openstack/nova","branch":"stable/icehouse","topic":"bug/1250751","id":"I2755c59b4db736151000dae351fd776d3c15ca39","number":"124161","subject":"Improve
shared storage checks for live migration","owner":{"name":"Jonathan
Proulx","email":"jon at jonproulx.com","username":"jproulx"},"url":"https://review.openstack.org/124161","commitMessage":"Improve
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
\u003crmoe at mirantis.com\u003e\nCo-authored-by: Yaguang Tang
\u003cyaguang.tang at canonical.com\u003e\nSigned-off-by: Dmitry Borodaenko
\u003cdborodaenko at mirantis.com\u003e\nChange-Id:
I2755c59b4db736151000dae351fd776d3c15ca39\n(cherry picked from commit
bc45c56f102cdef58840e02b609a89f5278e8cce)\n","createdOn":1411675113,"lastUpdated":1415792620,"sortKey":"0031135f0001e501","open":true,"status":"NEW"}
{"project":"openstack/nova","branch":"stable/icehouse","id":"I707a497bf534a88d55ba387b3f24f5eda7171f3a","number":"126212","subject":"Translation
update for German","owner":{"name":"Thomas
Goirand","email":"thomas at goirand.fr","username":"thomas-goirand"},"url":"https://review.openstack.org/126212","commitMessage":"Translation
update for German\n\nThis patch has been sent to the Debian bug tracker,
and I am\nnow forwarding it upstream.\n\nChange-Id:
I707a497bf534a88d55ba387b3f24f5eda7171f3a\n","createdOn":1412565399,"lastUpdated":1415792006,"sortKey":"003113550001ed04","open":true,"status":"NEW"}
{"type":"stats","rowCount":500,"runTimeMilliseconds":758}

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

Agreed.

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


-- 
Sean Dague
http://dague.net