Nova Pagination

Problem description
There is no current support for retrieving server data in a specific order, it is defaulted to descending sort order by the "created date" and "id" keys. In order to retrieve data in any sort order and direction, the REST APIs need to accept multiple sort keys and directions.

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 /servers and /servers/detail APIs will support the following parameters being repeated on the request: 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: /servers?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: /servers?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):
 * /servers
 * /servers/detail

Other End user impact
None. However, the novaclient could be updated to accept sort direction.

Deployer impact
None

Developer impact
None

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 cinder: https://blueprints.launchpad.net/cinder/+spec/cinder-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 the v2 and v3 APIs to retrieve the sort information and pass down to the DB layer (requires changes to compute/api.py, objects/instance.py, db/api.py, and db\sqlalchemy\api.py)

Dependencies

 * Related (but independent) change being proposed in cinder: https://blueprints.launchpad.net/cinder/+spec/cinder-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 /servers and /servers/detail API documentation will need to be updated to reflect the sorting parameters.