Difference between revisions of "Cinder Pagination"
| Line 18: | Line 18: | ||
For example: /volumes?sort_key=status&sort_key=display_name&sort_key=created_at&sort_dir=desc&sort_dir=desc&sort_dir=desc | For example: /volumes?sort_key=status&sort_key=display_name&sort_key=created_at&sort_dir=desc&sort_dir=desc&sort_dir=desc | ||
<br /> | <br /> | ||
| − | '''Note:''' The | + | '''Note:''' The "created_at" and "id" sort keys are always appended at the end of the key list (descending sort order) if they are not already specified on the request. |
<br/><br/> | <br/><br/> | ||
The database layer already supports multiple sort keys and directions. This blueprint will update the API layer to retrieve the sort information from the API request and pass that information down to the database layer. | The database layer already supports multiple sort keys and directions. This blueprint will update the API layer to retrieve the sort information from the API request and pass that information down to the database layer. | ||
Revision as of 19:06, 20 March 2014
Contents
Problem description
Pagination allows for retrieving a limited number of results instead of the entire data set. The cinder /volumes and /volumes/detail APIs support pagination and only support a single sort key and sort direction. The REST APIs need to accept multiple sort keys and directions so that the caller has more control over the sort order of the data set.
Use Case
A UI that displays a table with only the page of data that it has retrieved from the server. The items in this table need to be sorted by status first and by display name second. In order to retrieve data in this order, the APIs must accept multiple sort keys/directions.
Proposed change
The /volumes and /volumes/detail APIs will support the following parameters being repeated on the request:
| Parameter | Description |
|---|---|
| sort_key | Key used to determine sort order |
| sort_dir | Direction for with the associated sort key (asc or desc) |
The caller can specify these parameters multiple times in order to generate a list of sort keys and sort directions. The first key listed is the primary key, the next key is the secondary key, etc.
For example: /volumes?sort_key=status&sort_key=display_name&sort_key=created_at&sort_dir=desc&sort_dir=desc&sort_dir=desc
Note: The "created_at" and "id" sort keys are always appended at the end of the key list (descending sort order) if they are not already specified on the request.
The database layer already supports multiple sort keys and directions. This blueprint will update the API layer to retrieve the sort information from the API request and pass that information down to the database layer.
Alternatives
Repeating parameter key/values was chosen because glance already did it:
https://github.com/openstack/glance/blob/master/glance/api/v2/images.py#L526
However, the list of sort keys and directions could be built by splitting the associated parameter values.
For example: /volumes?sort_key=status,display_name,created_at&sort_dir=desc,desc,desc
The downside of this approach is that it would require pre-defined token characters. I'm open to this solution if it is deemed better.
REST API impact
The following APIs will support multiple sort keys and directions (v2 and v3):
- /volumes
- /volumes/detail
Other End user impact
None. However, the cinderclient could be updated to accept sort direction.
Deployer impact
None
Developer impact
None
Implementation
Assignee(s)
Primary assignee: Steven Kaufer
Other contributors
None
Milestones
Originally approved for: Unknown
Completed: None
Work Items
Ideally the logic for processing the sort parameters would be common to all components and would be done in oslo (a similar blueprint is also being proposed in nova: https://blueprints.launchpad.net/nova/+spec/nova-pagination)
Therefore, I see 2 work items:
- Create common function to process the API parameters and create a list of sort keys and directions
- Update v2 and v3 APIs to retrieve the sort information and pass down to the DB layer (requires changes to volume/api.py, db/api.py, and db\sqlalchemy\api.py)
Dependencies
- Related (but independent) change being proposed in nova: https://blueprints.launchpad.net/nova/+spec/nova-pagination
Testing
Tests need to be created to ensure that the data is retrieved in the specified sort order. I feel this unit tests are sufficient since these APIs already query the DB with multiple sort keys and directions ("created_at" and "id"); this blueprint is not adding support for multiple sort keys at the DB layer, only for exposing this function at the API level.
Documentation Impact
The /volumes and /volumes/detail API documentation will need to be updated to reflect the sorting parameters.
