To reduce load on the service, list operations will
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
parameters limit and
marker 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. Items are
sorted by create time in descending order. When a
create time is not available they are sorted by ID.
The limit parameter sets the
page size. Both parameters are optional. If the client
requests a limit beyond that
which is supported by the deployment an overLimit
(413) fault may be thrown.
A marker with an invalid ID will return a badRequest
(400) fault.
For convenience, collections are required to contain
atom "next" links. They may optionally also contain
"previous" links. The last page in the list will not
contain a "next" link. The following examples
illustrate three pages in a collection of images. The
first page was retrieved via a GET to
http://servers.api.openstack.org/v2/1234/images?limit=1.
In these examples, the limit
parameter sets the page size to a single item.
Subsequent links will honor the initial page size.
Thus, a client may follow links to traverse a
paginated collection without having to input the
marker parameter.
Example 1.12. Images collection: XML (first page)
<?xml version="1.0" encoding="UTF-8"?>
<images xmlns="http://docs.openstack.org/compute/api/v1.1"
xmlns:atom="http://www.w3.org/2005/Atom">
<image id="52415800-8b69-11e0-9b19-734f6f006e54" name="CentOS 5.2">
<atom:link rel="self"
href="http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
/>
</image>
<atom:link rel="next"
href="http://servers.api.openstack.org/v2/1234/images?limit=1&marker=52415800-8b69-11e0-9b19-734f6f006e54"
/>
</images>
Example 1.13. Images collection: JSON (first page)
{
"images": [
{
"id": "52415800-8b69-11e0-9b19-734f6f006e54",
"name": "CentOS 5.2",
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
}
]
}
],
"images_links" : [
{
"rel": "next",
"href": "http://servers.api.openstack.org/v2/1234/images?limit=1&marker=52415800-8b69-11e0-9b19-734f6f006e54"
}
]
}
Example 1.14. Images collection: XML (second page)
<?xml version="1.0" encoding="UTF-8"?>
<images xmlns="http://docs.openstack.org/compute/api/v1.1"
xmlns:atom="http://www.w3.org/2005/Atom">
<image id="52415800-8b69-11e0-9b19-734f5736d2a2" name="My Server Backup">
<atom:link
rel="self"
href="http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"/>
</image>
<atom:link rel="next"
href="http://servers.api.openstack.org/v2/1234/images?limit=1&marker=52415800-8b69-11e0-9b19-734f5736d2a2"/>
</images>
Example 1.15. Images collection: JSON (second page)
{
"images" : [
{
"id" : "52415800-8b69-11e0-9b19-734f5736d2a2",
"name" : "My Server Backup",
"links": [
{
"rel" : "self",
"href" : "http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f5736d2a2"
}
]
}
],
"images_links": [
{
"rel" : "next",
"href" : "http://servers.api.openstack.org/v2/1234/images?limit=1&marker=52415800-8b69-11e0-9b19-734f5736d2a2"
}
]
}
Example 1.16. Images collection: XML (last page)
<?xml version="1.0" encoding="UTF-8"?>
<images xmlns="http://docs.openstack.org/compute/api/v1.1"
xmlns:atom="http://www.w3.org/2005/Atom">
<image id="52415800-8b69-11e0-9b19-734f6ff7c475"
name="Backup 2">
<atom:link
rel="self"
href="http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6ff7c475"/>
</image>
</images>
Example 1.17. Images collection: JSON (last page)
{
"images": [
{
"id": "52415800-8b69-11e0-9b19-734f6ff7c475",
"name": "Backup 2",
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6ff7c475"
}
]
}
]
}
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. It
also allows collections to be embedded in other
objects as illustrated below. Here, a subset of
metadata items are presented within the image. Clients
must follow the "next" link to retrieve the full set
of metadata.
Example 1.18. Paginated image metadata: XML
<?xml version="1.0" encoding="UTF-8"?>
<image
xmlns="http://docs.openstack.org/compute/api/v1.1"
xmlns:atom="http://www.w3.org/2005/Atom"
id="52415800-8b69-11e0-9b19-734f6f006e54"
name="CentOS 5.2">
<metadata>
<meta key="ImageVersion">1.5</meta>
<meta key="ImageType">Gold</meta>
<atom:link
rel="next"
href="http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54/meta?marker=ImageType"/>
</metadata>
<atom:link
rel="self"
href="http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"/>
</image>
Example 1.19. Paginated image metadata: JSON
{
"image": {
"id": "52415800-8b69-11e0-9b19-734f6f006e54",
"name": "CentOS 5.2",
"metadata": {
"ImageVersion": "1.5",
"ImageType": "Gold"
},
"metadata_links": [
{
"rel": "next",
"href": "http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54/meta?marker=ImageType"
}
],
"links": [
{
"rel": "self",
"href": "http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54"
}
]
}
}
