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 (e.g.
?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_key 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_key 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.
