To reduce load on the service, list operations return a maximum of 20 items at a time. This is referred to as pagination. Cloud Databases has separate paging limits for instances, databases, and users, which are currently all set to 20. If a request supplies no limit or one that exceeds the configured default limit, the default is used instead.
Pagination provides the ability to limit the size
of the returned data as well as retrieve a specified
subset of a large data set. Pagination has two key
concepts: limit and marker. Limit
is the restriction on the maximum number of items for
that type that can be returned.
Marker is the ID of the last
item in the previous list returned. The ID is the UUID
in the case of instances, and the name in the case of
databases and users. For example, a query could
request the next 10 instances after the instance
"1234" as follows:
?limit=10&marker=1234. Items are
displayed sorted by ID.
Pagination applies only to the calls listed in the following table:
| Verb | URI | Description | |||
| GET | /instances/ | Lists the status and information for all database instances. | |||
| GET | /instances/{instanceId}/databases | Lists databases for the specified instance. | |||
| GET | /instances/{instanceId}/users | Lists the users in the specified database instance. | |||
If the content returned by a call is paginated, the
response includes a structured link much like an
instance item's links, with the basic structure
{"href": "<url>", "rel": "next"}.
Any response that is truncated by pagination will have
a next link, which points to the
next item in the collection. If there are no more
items, no next link is
returned.
See the examples of paged List Instances calls that follow.
Reviewer: Need new examples that show OpenStack host.
Example 3.3. List Instances Paged Request: XML
GET /v1.0/1234/instances?limit=2 HTTP/1.1
User-Agent: python-reddwarfclient
Host: openstack.example.com
X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
Accept: application/xml
Content-Type: application/xml
Example 3.4. List Instances Paged Request: JSON
GET /v1.0/1234/instances?limit=2 HTTP/1.1
User-Agent: python-reddwarfclient
Host: openstack.example.com
X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
Accept: application/json
Content-Type: application/json
Notice that the paged request examples above set the
limit to 2 (?limit=2), so the responses
that follow each show 2 instances and return a
marker set to the UUID of the
last item in the returned list
(?marker=4137d6a4-03b7-4b66-b0ef-8c7c35c470d3).
Also a link is provided to retrieve the next 2 results
(limit=2) in the link element
identified by the attribute rel="next"
(XML) or "rel":"next" (JSON):
Example 3.5. List Instances Paged Response: XML
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 1538
Date: Mon, 18 Mar 2013 19:09:17 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
<instances xmlns="http://docs.openstack.org/database/api/v1.0">
<instance id="098653ba-218b-47ce-936a-e0b749101f81" name="xml_rack_instance" status="ACTIVE">
<links>
<link href="https://openstack.example.com/v1.0/1234/instances/098653ba-218b-47ce-936a-e0b749101f81" rel="self"/>
<link href="https://openstack.example.com/instances/098653ba-218b-47ce-936a-e0b749101f81" rel="bookmark"/>
</links>
<volume size="2"/>
<flavor id="1">
<links>
<link href="https://openstack.example.com/v1.0/1234/flavors/1" rel="self"/>
<link href="https://openstack.example.com/flavors/1" rel="bookmark"/>
</links>
</flavor>
</instance>
<instance id="44b277eb-39be-4921-be31-3d61b43651d7" name="json_rack_instance" status="ACTIVE">
<links>
<link href="https://openstack.example.com/v1.0/1234/instances/44b277eb-39be-4921-be31-3d61b43651d7" rel="self"/>
<link href="https://openstack.example.com/instances/44b277eb-39be-4921-be31-3d61b43651d7" rel="bookmark"/>
</links>
<volume size="2"/>
<flavor id="1">
<links>
<link href="https://openstack.example.com/v1.0/1234/flavors/1" rel="self"/>
<link href="https://openstack.example.com/flavors/1" rel="bookmark"/>
</links>
</flavor>
</instance>
<links>
<link href="https://openstack.example.com/v1.0/1234/instances?marker=44b277eb-39be-4921-be31-3d61b43651d7&limit=2" rel="next"/>
</links>
</instances>
Example 3.6. List Instances Paged Response: JSON
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1172
Date: Mon, 18 Mar 2013 19:09:17 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
{
"instances": [
{
"flavor": {
"id": "1",
"links": [
{
"href": "https://openstack.example.com/v1.0/1234/flavors/1",
"rel": "self"
},
{
"href": "https://openstack.example.com/flavors/1",
"rel": "bookmark"
}
]
},
"id": "098653ba-218b-47ce-936a-e0b749101f81",
"links": [
{
"href": "https://openstack.example.com/v1.0/1234/instances/098653ba-218b-47ce-936a-e0b749101f81",
"rel": "self"
},
{
"href": "https://openstack.example.com/instances/098653ba-218b-47ce-936a-e0b749101f81",
"rel": "bookmark"
}
],
"name": "xml_rack_instance",
"status": "ACTIVE",
"volume": {
"size": 2
}
},
{
"flavor": {
"id": "1",
"links": [
{
"href": "https://openstack.example.com/v1.0/1234/flavors/1",
"rel": "self"
},
{
"href": "https://openstack.example.com/flavors/1",
"rel": "bookmark"
}
]
},
"id": "44b277eb-39be-4921-be31-3d61b43651d7",
"links": [
{
"href": "https://openstack.example.com/v1.0/1234/instances/44b277eb-39be-4921-be31-3d61b43651d7",
"rel": "self"
},
{
"href": "https://openstack.example.com/instances/44b277eb-39be-4921-be31-3d61b43651d7",
"rel": "bookmark"
}
],
"name": "json_rack_instance",
"status": "ACTIVE",
"volume": {
"size": 2
}
}
],
"links": [
{
"href": "https://openstack.example.com/v1.0/1234/instances?marker=44b277eb-39be-4921-be31-3d61b43651d7&limit=2",
"rel": "next"
}
]
}
