Cisco Evolved Programmable Network Manager API
Evolved Programmable Network Manager API Documentation

Using Paging

Paging lets you control the number of records returned by a request and page through the results. Check the documentation for each request type to see if it supports Paging.

Paging via the query string

To page results, use the .maxResults and .firstResult parameters. For example...

	/webacs/api/v1/data/Devices?.full=true&.firstResult=0&.maxResults=4

would get the first four results (0-3). And...

	/webacs/api/v1/data/Devices?.full=true&.maxResults=4&.firstResult=4

would get the next four results (4-7).

The response contains information about the full result set and the paging that was used:

              	<queryResponse 
              		last="7" first="4" count="24"
              		type="Devices" 
              		rootUrl="https://my_server/webacs/api/v1/data" 
              		requestUrl="https://my_server/webacs/api/v1/data/Devices?.full=true&.maxResults=4&.firstResult=4" 
              		responseType="listEntityInstances">
              		....
              	

Paging via the Range HTTP header

One can also use a HTTP header to control the paging. The Range header using a type of 'instances' can be added to a request instead of using the query parameters.

For example, this header would get the first 4 results:

				Range:instances=0-3
				

The request/response for this would be:

> GET /webacs/api/v1/data/Devices HTTP/1.1
> User-Agent: curl/7.28.1
> Host: my_server
> Accept: */*
> Range:instances=0-3
> 
< HTTP/1.1 200 OK
< Content-Type: text/xml
< Content-Range: instances 0-3/14
< Content-Length: 607
< 
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<queryResponse last="3" first="0" count="14" responseType="listEntityIds" 
    requestUrl="https://my_server/webacs/api/v1/data/Devices" 
    rootUrl="https://my_server/webacs/api/v1/data/Devices" type="Devices"> 
    ....             	
              	

Note: The url parameters .firstResult and .maxResults will override the header range value

Page Size Limits

When using either the query string or the HTTP header for paging, there is a limit of 1000 results per request. This limit can be configured.

Paging Over Volatile Data Sets

Sometimes, when issuing queries to a resource to get pages of data, the data set changes. To mitigate this, consider paging via filtering instead of paging with .firstResult. For instance, if paging over Historical Client Statistics, data that is older than the retention period (24 hours by default) will be removed. These records will be at the beginning of the data set (when .firstResult is 0). Their deletion means records slightly newer than them will move to the beginning of the data set. If this occurs when you are paging through the data, you will miss some records.

Here's how to page via filtering and mitigate volatility:

  1. Request your first page without specifying any sorting (specifying a sort parameter will make these steps yield incorrect results).
  2. Note the id of the last record returned. We'll call it <last_record_id>
  3. Request the next page, leaving .firstResult unspecified and filtering with id=gt(<last_record_id>).
  4. Repeat the previous two steps until you've acquired all of the data you need.