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

Brand New Entity 127.0.0.4 127.0.0.5 127.0.0.6 127.0.0.7 kinds stuff go null is not a valid value 1 1 enBBBB [https://cmbeta.api.rackspacecloud.com/v1.0/entities?limit=1&marker=enBBBB]();

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

Brand New Entity 2 127.0.0.4 127.0.0.5 127.0.0.6 127.0.0.7 kinds 1 1 enBBBB

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.