From f9767f5c10c837c961dd0b05e9fe9ab1cd9fc37a Mon Sep 17 00:00:00 2001 From: zhongjun Date: Fri, 8 Sep 2017 11:20:13 +0800 Subject: [PATCH] Add count info in /shares and /shares/detail response This blueprint proposes adding total count info in Manila's /shares and /shares/detail APIs. Partially-Implements bp add-amount-info-in-list-api Change-Id: I12c41a46140b07f76565d8934e0326480477c623 --- specs/queens/README.rst | 2 - .../add-count-info-in-list-response.rst | 207 ++++++++++++++++++ 2 files changed, 207 insertions(+), 2 deletions(-) delete mode 100644 specs/queens/README.rst create mode 100644 specs/queens/add-count-info-in-list-response.rst diff --git a/specs/queens/README.rst b/specs/queens/README.rst deleted file mode 100644 index 1d6c5f7..0000000 --- a/specs/queens/README.rst +++ /dev/null @@ -1,2 +0,0 @@ -Add Queens release specs in this folder -======================================= diff --git a/specs/queens/add-count-info-in-list-response.rst b/specs/queens/add-count-info-in-list-response.rst new file mode 100644 index 0000000..8f2050a --- /dev/null +++ b/specs/queens/add-count-info-in-list-response.rst @@ -0,0 +1,207 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +==================================================== +Show resource's total count info in share list APIs +==================================================== + +https://blueprints.launchpad.net/manila/+spec/add-amount-info-in-list-api + + +This blueprint proposes adding total count info in Manila's /shares +and /shares/detail APIs. + +Problem description +=================== + +Show how many resources a user or tenant has is usually required in the web +portal's summary section, but we cannot get this info now. In order to show +this kind of total number to the end user, many clouds have to collect all of +the resources. + +Use Cases +========= + +The administrators or users to know how many resources they have in total +without retrieving and accumulating them all when it return just a slice +of paginated list. + +Proposed change +=============== + +According to the openstack API-WG `[1]`_ proposal. It provide guidance on +returning the total size of a resource collection in a project's public REST +API. + +So this bp proposes to add new attribute ``count`` in our /shares and +/shares/detail APIs to having the total count information in /shares and +/shares/detail APIs response. If we add the ``count`` attribute +into our response body in default, it could has a performance impact if +we have a mount of resources, considering not every request requires +this kind of info, the additional query parameter is required to turn +this on when listing resource. + +Alternatives +------------ + +There are few alternative solutions for this requirement, let's list and +compare them all here. + +1. Add amount information in response header:: + + X-resource-count: 200 + +The disadvantage of this is it will add some burden to the API customers, +we don't have any history for adding useful content in response +headers. Also it makes more difficult for documentation. + +2. Add explicit API for each resources:: + + POST: /v2/{tenant_id}/{resources}/action {os-count} + +This change involves a lot of modifications and creates several new APIs. +Adding this amount of APIs for such a simple API change is overdesign. + +3. Create a new API for different resources:: + + POST: /V3/{tenant_id}/action {os-count} + BODY: + { + "resource": "share", + "user": "user_1", + "other_filter": "other_value" + } + +For this change, one more API request is required if the end user wants to +know how many resources in total when listing resources. + + +Data model impact +----------------- + +None + +REST API impact +--------------- + +Microversion bump is required for this change. + +Add the 'with_count' parameter in query string in share list API, it +is used to indicate if the total count of resources should or should +not be returned from a GET REST API request. Any value that equates to +True indicates that the count should be returned. Conversely, any value +that equates to False indicates that the count should not be returned. + +* List shares + + * URL: /v2/{tenant_id}/shares?with_count=true + * Method: POST + * JSON body: + + .. code:: json + + { + 'shares': [{ + 'name': 'test', + ... + }] + 'count': , + } + +* List shares with details + + * URL: /v2/{tenant_id}/shares/detail?with_count=true + * Method: POST + * JSON body: + + .. code:: json + + { + 'shares': [{ + 'name': 'test', + ... + }] + 'count': , + } + +Client impact +------------- + +The share list command will be upgraded to support this. + +Security impact +--------------- + +None + +Notifications impact +-------------------- + +None + +Other end user impact +--------------------- + +None + +Performance Impact +------------------ + +Since we will add additional ``COUNT()`` statement if the list +APIs are requested with the ``with_count`` option, there would be a +performance impact on those APIs, especially when there are a lot +of data in database. + +Other deployer impact +--------------------- + +None + +Developer impact +---------------- + +None + +Implementation +============== + +Assignee(s) +----------- + +Primary assignee: + zhongjun(jun.zhongjun2@gmail.com) + +Work Items +---------- + +* Add ``with_count`` option support in share list APIs. +* Add related unit testcases. +* Update manila-client. +* Update manila-ui. + +Dependencies +============ + +None + +Testing +======= + +* Add unit tests and tempest test to cover this change. + +Documentation Impact +==================== + +Update API documentation. + +References +========== + +_`[1]`: http://specs.openstack.org/openstack/api-wg/guidelines/counting.html + + + +