Bug 1044270

Cloned from launchpad blueprint https://blueprints.launchpad.net/keystone/+spec/pagination.

Description:

The current state of pagination is an unknown. There were supposed to be a session in IceHouse summit to *kill pagination* but it never materialized. The use cases for pagination remains.

1. A UI (i.e. Horizon) for Keystone needs an intuitive and consistent way to list the resources via public APIs.
2. Users need an intuitive and consistent way to list the resources via public APIs without having the cloud providers to open up their database for them. This is not just about reporting and auditing.

The arguments against pagaination is well understood.

1. Pagination is open to abuse. For example, if a Keystone backend, misconfigured or otherwise, may take a long time to satisfy a generic query and could potentially return massive amount of data.
2. Pagination may hurt user experience. See http://lists.openstack.org/pipermail/openstack-dev/2013-August/013582.html

However, neither are showstoppers for pagination. Yes, anything is open to abuse if cloud providers/operators are not careful. Same goes with performance, security, supportability, etc. A user who interacts with two different cloud providers may come away with vastly different user experience, even if the cloud providers are using the same OpenStack code. From API perspective, pagination is needed and useful to have.

Lets re-introduce the pagination parameters ``page`` and ``per_page``. 

``page`` indicates the current page the user is seeking. It must be a positive integer. It is an optional parameter for the listing APIs. If absent, it is always default to ``1``. An implementation may also impose an upper limit on it. If the given ``page`` exceeds the imposed limit, an implementation must response with an HTTP code 400 (Bad Request).

``per_page`` indicates the number of items per page. It must be a positive integer. It is an optional parameter for the listing APIs. If absent, an implementation must set a default value. An implementation may also impose an upper limit on it. If the given ``page`` exceeds the imposed limit, an implementation must response with an HTTP code 400 (Bad Request).


The imposed limit should alleviate the concerns with abuse and user experience.

Examples:

GET /v3/users?page=3,per_page=10

Specification URL (additional information):

None