Open Stack

I have proposed an addition to the REST API doc for cinder to add
sorting to the GET volumes queries [1]. While doing this work, I
noticed that the pagination parameters (eg, limit/marker) were
missing from the cinder documentation. I have looked at how the
other projects have documented this and I see that they are not
consistent.

For example:

Compute v2:
* limit: Integer value for the limit of values to return.
* marker: UUID of the <server/flavor/image> at which you want to set a
marker.

Identity v2:
* limit: The page size.
* marker: The ID of the last item in the previous list.

Image v2:
* limit: Use to request a specific page size. Expect a response to a
limited request to return between zero and limit items. The typical
pattern of limit and marker is to make an initial limited request and
then to use the ID of the last image from the response as the marker
parameter in a subsequent limited request.
* marker: Specifies the ID of the last-seen image. The typical pattern
of limit and marker is to make an initial limited request and then to
use the ID of the last image from the response as the marker parameter
in a subsequent limited request.

Object Storage v1:
* limit: For an integer value n, limits the number of results to n.
* marker: For a string value x, returns container names that are
greater in value than the specified marker.

Orchestration v1:
* limit: Limits the number of stacks that appear on a page to this
value. The typical pattern of limit and marker is to make an initial
limited request and then to use the ID of the last stack from the
response as the marker parameter in a subsequent limited request.
* marker: Specifies the ID of the last-seen stack. The typical
pattern of limit and marker is to make an initial limited request
and then to use the ID of the last stack from the response as the
marker parameter in a subsequent limited request.

Telemetry v1:
* limit: Maximum number of samples to return.

IMO, instead of adding yet another definition for the limit/marker
parameters for cinder, the definition of these parameters could be
made generic and shared across all projects.

I see that there is no cross-project equivalent common.ent file. Any
thoughts or objections to creating one and then updating the above
projects to use it for limit and marker? Obviously the parameter
definitions needs to be made generic and we can use a gerrit review
to hash out those details.

Thanks for the feedback!

[1] https://review.openstack.org/#/c/160550/

Steven Kaufer
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150303/701baf44/attachment.html>