Merge "Add count info in /shares and /shares/detail response"

This commit is contained in:
Zuul 2017-10-19 02:53:14 +00:00 committed by Gerrit Code Review
commit 8f194e4787
2 changed files with 207 additions and 2 deletions

View File

@ -1,2 +0,0 @@
Add Queens release specs in this folder
=======================================

View File

@ -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': <int_count>,
}
* List shares with details
* URL: /v2/{tenant_id}/shares/detail?with_count=true
* Method: POST
* JSON body:
.. code:: json
{
'shares': [{
'name': 'test',
...
}]
'count': <int_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