nova/api-guide/source/paginated_collections.rst
Takashi NATSUME ddf7c6e370 Improve formats of the Compute API guide
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
2018-11-07 04:01:40 +00:00

74 lines
2.9 KiB
ReStructuredText

=====================
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:
.. code::
?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)**
.. code::
{
"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.