Paginated collections

To reduce load on the service, list operations will return a maximum number of items at a time. To navigate the collection, the parameters limit and marker can be set in the URI, for example ?limit=200&marker=enCCCCCC. The marker parameter is the ID of a first item in the next page. This item can be found in the metadata object under the next_marker tag. Items are sorted by the ID name in a lexicographic order. The limit parameter sets the page size. It defaults to 100 items per page and the maximum value is 1000. Both parameters are optional. If the client requests a limit beyond that which is not supported an invalidLimit (400) fault may be thrown.

For convenience, collections contain a link to the next page (the next_href attribute in the metadata object). If there are no more objects, the next_marker and next_href attributes will be empty. The following examples illustrate two pages in a collection of entities. The first page was retrieved via a GET to https://monitoring.api.rackspacecloud.com/v1.0/entities?limit=1. In these examples, the limit parameter sets the page size to a single item. Subsequent next_href link will honor the initial page size. Thus, a client may follow this link to traverse a paginated collection without having to input the limit parameter.

Example 3.8. List Entities, First Page: XML

<?xml version="1.0" encoding="utf-8"?>
<container>
  <values>
    <entity key="enAAAAA">
      <label>Brand New Entity</label>
      <ip_addresses>
        <a>127.0.0.4</a>
        <b>127.0.0.5</b>
        <c>127.0.0.6</c>
        <test>127.0.0.7</test>
      </ip_addresses>
      <metadata>
        <all>kinds</all>
        <of>stuff</of>
        <can>go</can>
        <here>null is not a valid value</here>
      </metadata>
    </entity>
  </values>
  <metadata>
    <count>1</count>
    <limit>1</limit>
    <marker/>
    <next_marker>enBBBB</next_marker>
    <next_href>https://cmbeta.api.rackspacecloud.com/v1.0/entities?limit=1&marker=enBBBB</next_href>
  </metadata>
</container>

Example 3.9. List Entities, First Page: JSON

{
    "values": [
        {
            "key": "enAAAAA",
            "label": "Brand New Entity",
            "ip_addresses": {
                "a": "127.0.0.4",
                "b": "127.0.0.5",
                "c": "127.0.0.6",
                "test": "127.0.0.7"
            },
            "metadata": {
                "all": "kinds",
                "of": "stuff",
                "can": "go",
                "here": "null is not a valid value"
            }
        }
    ],
    "metadata": {
        "count": 1,
        "limit": 1,
        "marker": null,
        "next_marker": "enBBBB",
        "next_href": "https://cmbeta.api.rackspacecloud.com/v1.0/entities?limit=1&marker=enBBBB"
    }
}

Example 3.10. List Entities, Second Page: XML

<?xml version="1.0" encoding="utf-8"?>
<container>
  <values>
    <entity key="enBBBB">
      <label>Brand New Entity 2</label>
      <ip_addresses>
        <a>127.0.0.4</a>
        <b>127.0.0.5</b>
        <c>127.0.0.6</c>
        <test>127.0.0.7</test>
      </ip_addresses>
      <metadata>
        <all>kinds</all>
      </metadata>
    </entity>
  </values>
  <metadata>
    <count>1</count>
    <limit>1</limit>
    <marker>enBBBB</marker>
    <next_marker/>
    <next_href/>
  </metadata>
</container>

Example 3.11. List Entities, Second Page: JSON

{
    "values": [
        {
            "key": "enBBBB",
            "label": "Brand New Entity 2",
            "ip_addresses": {
                "a": "127.0.0.4",
                "b": "127.0.0.5",
                "c": "127.0.0.6",
                "test": "127.0.0.7"
            },
            "metadata": {
                "all": "kinds"
            }
        }
    ],
    "metadata": {
        "count": 1,
        "limit": 1,
        "marker": "enBBBB",
        "next_marker": null,
        "next_href": null
    }
}

In the JSON representation, paginated collections contain a values property that contains the items in the collection. The link to the next page is located in the metadata object (metadata.next_href attribute). Clients must follow the next_href link to continue to retrieve additional entities belonging to an account.