Replace the 'NOTE' and 'TODO' words with the note and todo directives in the Compute API guide. Improve some format in the guide. e.g. Fix unnecessary bold characters. Change-Id: I7e9d6b8a5228886fd5de03d12482481d2b652666 Closes-Bug: #1558459
2.9 KiB
Paginated collections
To reduce load on the service, list operations return a maximum
number of items at a time. The maximum number of items returned is
determined by the compute provider. To navigate the collection, the
limit
and marker
parameters can be set in the
URI. For example:
?limit=100&marker=1234
The marker
parameter is the ID of the last item in the
previous list. By default, the service sorts items by create time in
descending order. When the service cannot identify a create time, it
sorts items by ID. The limit
parameter sets the page size.
Both parameters are optional. If the client requests a
limit
beyond one that is supported by the deployment an
overLimit (413) fault may be thrown. A marker with an invalid ID returns
a badRequest (400) fault.
For convenience, collections should contain atom next
links. They may optionally also contain previous
links but
the current implementation does not contain previous
links.
The last page in the list does not contain a link to "next" page. The
following examples illustrate three pages in a collection of servers.
The first page was retrieved through a GET to http://servers.api.openstack.org/v2.1/servers?limit=1.
In these examples, the ``limit`` parameter sets the page size
to a single item. Subsequent links honor the initial page size. Thus, a
client can follow links to traverse a paginated collection without
having to input the marker
parameter.
Example: Servers collection: JSON (first page)
{
"servers_links":[
{
"href":"https://servers.api.openstack.org/v2.1/servers?limit=1&marker=fc45ace4-3398-447b-8ef9-72a22086d775",
"rel":"next"
}
],
"servers":[
{
"id":"fc55acf4-3398-447b-8ef9-72a42086d775",
"links":[
{
"href":"https://servers.api.openstack.org/v2.1/servers/fc45ace4-3398-447b-8ef9-72a22086d775",
"rel":"self"
},
{
"href":"https://servers.api.openstack.org/v2.1/servers/fc45ace4-3398-447b-8ef9-72a22086d775",
"rel":"bookmark"
}
],
"name":"elasticsearch-0"
}
]
}
In JSON, members in a paginated collection are stored in a JSON array
named after the collection. A JSON object may also be used to hold
members in cases where using an associative array is more practical.
Properties about the collection itself, including links, are contained
in an array with the name of the entity an underscore (_) and
links
. The combination of the objects and arrays that start
with the name of the collection and an underscore represent the
collection in JSON. The approach allows for extensibility of paginated
collections by allowing them to be associated with arbitrary
properties.