1.5. 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. 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 returns 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 does not contain a "next" link. The following examples illustrate three pages in a collection of images. The first page was retrieved through 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 honor the initial page size. Thus, a client can 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&amp;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&amp;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"
            }
        ]
    }
}

Questions? Discuss on ask.openstack.org
Found an error? Report a bug against this page