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, marker and page_reverse can be set in the URI. For example:
?limit=100&marker=1234&page_reverse=False
The marker
parameter is the
ID of the last item in the previous list. The
limit
parameter sets the
page size. The page_reverse
parameter sets the page direction. These parameters
are optional. If the client requests a limit beyond
the maximum limit configured by the deployment, the
server returns the maximum limit number of
items.
For convenience, list responses contain atom "next" links and "previous" links. The last page in the list requested with 'page_reverse=False' will not contain "next" link, and the last page in the list requested with 'page_reverse=True' will not contain "previous" link. The following examples illustrate two pages with three items. The first page was retrieved through:
GET http://127.0.0.1:9696/v2.0/networks.json?limit=2
Pagination is an optional feature of OpenStack Networking API, and it might be disabled. If pagination is disabled, the pagination parameters will be ignored and return all the items.
If a particular plug-in does not support pagination operations, and pagination is enabled, the Networking API v2.0 will emulate the pagination behavior so that users can expect the same behavior regardless of the particular plug-in running in the background.
Unfortunately OpenStack Networking does not expose any mechanism to tell user if pagination is supported by particular plug-in or enabled.
Example 3.3. Network Collection, First Page: JSON Request
GET /v2.0/networks.json?limit=2 HTTP/1.1 Host: 127.0.0.1:9696 Content-Type: application/json Accept: application/json
Example 3.4. Network Collection, First Page: JSON Response
{ "networks": [ { "admin_state_up": true, "id": "396f12f8-521e-4b91-8e21-2e003500433a", "name": "net3", "provider:network_type": "vlan", "provider:physical_network": "physnet1", "provider:segmentation_id": 1002, "router:external": false, "shared": false, "status": "ACTIVE", "subnets": [], "tenant_id": "20bd52ff3e1b40039c312395b04683cf" }, { "admin_state_up": true, "id": "71c1e68c-171a-4aa2-aca5-50ea153a3718", "name": "net2", "provider:network_type": "vlan", "provider:physical_network": "physnet1", "provider:segmentation_id": 1001, "router:external": false, "shared": false, "status": "ACTIVE", "subnets": [], "tenant_id": "20bd52ff3e1b40039c312395b04683cf" } ], "networks_links": [ { "href": "http://127.0.0.1:9696/v2.0/networks.json?limit=2&marker=71c1e68c-171a-4aa2-aca5-50ea153a3718", "rel": "next" }, { "href": "http://127.0.0.1:9696/v2.0/networks.json?limit=2&marker=396f12f8-521e-4b91-8e21-2e003500433a&page_reverse=True", "rel": "previous" } ] }
Example 3.5. Network Collection, First Page: XML Request
GET /v2.0/networks.xml?limit=2 HTTP/1.1 Host: 127.0.0.1:9696 Content-Type: application/xml Accept: application/xml
Example 3.6. Network Collection, First Page: XML Response
<?xml version="1.0" ?> <networks xmlns="http://openstack.org/neutron/api/v2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:provider="http://docs.openstack.org/ext/provider/api/v1.0" xmlns:neutron="http://openstack.org/neutron/api/v2.0" xmlns:router="http://docs.openstack.org/ext/neutron/router/api/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <network> <status>ACTIVE</status> <subnets neutron:type="list"/> <name>net3</name> <provider:physical_network>physnet1</provider:physical_network> <admin_state_up neutron:type="bool">True</admin_state_up> <tenant_id>20bd52ff3e1b40039c312395b04683cf</tenant_id> <provider:network_type>vlan</provider:network_type> <router:external neutron:type="bool">False</router:external> <shared neutron:type="bool">False</shared> <id>396f12f8-521e-4b91-8e21-2e003500433a</id> <provider:segmentation_id neutron:type="long">1002</provider:segmentation_id> </network> <network> <status>ACTIVE</status> <subnets neutron:type="list"/> <name>net2</name> <provider:physical_network>physnet1</provider:physical_network> <admin_state_up neutron:type="bool">True</admin_state_up> <tenant_id>20bd52ff3e1b40039c312395b04683cf</tenant_id> <provider:network_type>vlan</provider:network_type> <router:external neutron:type="bool">False</router:external> <shared neutron:type="bool">False</shared> <id>71c1e68c-171a-4aa2-aca5-50ea153a3718</id> <provider:segmentation_id neutron:type="long">1001</provider:segmentation_id> </network> <atom:link href="http://127.0.0.1:9696/v2.0/networks.xml?limit=2&marker=71c1e68c-171a-4aa2-aca5-50ea153a3718" rel="next"/> <atom:link href="http://127.0.0.1:9696/v2.0/networks.xml?limit=2&marker=396f12f8-521e-4b91-8e21-2e003500433a&page_reverse=True" rel="previous"/> </networks>
The last page won't show the "next" links
Example 3.7. Network Collection, Last Page: JSON Request
GET /v2.0/networks.json?limit=2&marker=71c1e68c-171a-4aa2-aca5-50ea153a3718 HTTP/1.1 Host: 127.0.0.1:9696 Content-Type: application/json Accept: application/json
Example 3.8. Network Collection, Last Page: JSON Response
{ "networks": [ { "admin_state_up": true, "id": "b3680498-03da-4691-896f-ef9ee1d856a7", "name": "net1", "provider:network_type": "vlan", "provider:physical_network": "physnet1", "provider:segmentation_id": 1000, "router:external": false, "shared": false, "status": "ACTIVE", "subnets": [], "tenant_id": "c05140b3dc7c4555afff9fab6b58edc2" } ], "networks_links": [ { "href": "http://127.0.0.1:9696/v2.0/networks.json?limit=2&marker=b3680498-03da-4691-896f-ef9ee1d856a7&page_reverse=True", "rel": "previous" } ] }
Example 3.9. Network Collection, Last Page: XML Request
GET /v2.0/networks.xml?limit=2&marker=71c1e68c-171a-4aa2-aca5-50ea153a3718 HTTP/1.1 Host: 127.0.0.1:9696 Content-Type: application/xml Accept: application/xml
Example 3.10. Network Collection, Last Page: XML Response
<?xml version="1.0" ?> <networks xmlns="http://openstack.org/neutron/api/v2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:provider="http://docs.openstack.org/ext/provider/api/v1.0" xmlns:neutron="http://openstack.org/neutron/api/v2.0" xmlns:router="http://docs.openstack.org/ext/neutron/router/api/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <network> <status>ACTIVE</status> <subnets neutron:type="list"/> <name>net1</name> <provider:physical_network>physnet1</provider:physical_network> <admin_state_up neutron:type="bool">True</admin_state_up> <tenant_id>c05140b3dc7c4555afff9fab6b58edc2</tenant_id> <provider:network_type>vlan</provider:network_type> <router:external neutron:type="bool">False</router:external> <shared neutron:type="bool">False</shared> <id>b3680498-03da-4691-896f-ef9ee1d856a7</id> <provider:segmentation_id neutron:type="long">1000</provider:segmentation_id> </network> <atom:link href="http://127.0.0.1:9696/v2.0/networks.xml?limit=2&marker=b3680498-03da-4691-896f-ef9ee1d856a7&page_reverse=True" rel="previous"/> </networks>