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