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":"j...@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 \u003cr...@mirantis.com\u003e\nCo-authored-by: Yaguang Tang \u003cyaguang.t...@canonical.com\u003e\nSigned-off-by: Dmitry Borodaenko \u003cdborodae...@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":"tho...@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@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 http://dague.net _______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev