Pagination Docs Snippet

gistfile1.md

Pagination

Select APIs support pagination, the ability to return a subset of the results, with a key to the next set of results. Currently, only the following APIs have pagination enabled:

• Accounts
• CDRs

Let's take a look at the CDRs API to see how to interpret pagination.

CDR Pagination

We start with the typical CDR request for a listing of CDRs:

curl -v -H "X-Auth-Token: {AUTH_TOKEN}" -H "Content-Type: application/json" http://{SERVER_URL}:8000/v1/accounts/{ACCOUNT_ID}/cdrs
{"auth_token": "{AUTH_TOKEN}"
 ,"data": [{CDR_OBJECT}
           ,{CDR_OBJECT}
           ,...
          ]
 ,"next_start_key": 63566193143
 ,"page_size": 25
 ,"request_id": "e8e7a793986ba86f15bd0c7b2ce91233"
 ,"revision": "bfcd0b7d8cbd647eaea262cb05be1b8b"
 ,"start_key": 63565345339
 ,"status": "success"
}

The pagination response keys are next_start_key, page_size, and start_key.

• next_start_key: used to get the next page of results from this API. Will not exist if this is the last page.
• start_key: used to get back to this page of results (or start pagination from this point)
• page_size: the number of results returned in this page

Assuming no changes are made to the underlying documents, start_key will get you this page of results, and next_start_key will give you a pointer to the next page (imagine a linked-list).

Requesting a page

Using the next_start_key value, let's request the next page of CDRs:

curl -v -H "X-Auth-Token: {AUTH_TOKEN}" -H "Content-Type: application/json" http://{SERVER_URL}:8000/v1/accounts/{ACCOUNT_ID}/cdrs?start_key=63566193143
{"auth_token": "{AUTH_TOKEN}"
 ,"data": [{CDR_OBJECT}
           ,{CDR_OBJECT}
           ,...
          ]
 ,"next_start_key": 63566542092
 ,"page_size": 25
 ,"request_id": "7256dc9201b6168305e883729b688d40"
 ,"revision": "627d3a28af809ad745c2fbfc8b7397a1"
 ,"start_key": 63566193143
 ,"status": "success"
}

Observe now that start_key is the requested start_key and next_start_key points to the start of the next page of results.

&tip If next_start_key is missing from the response envelope, the response represents the last page of results.

You can also choose to receive pages in bigger or smaller increments by specifying page_size on the request. Do take care, as the next_start_key will probably vary if you use the same start_key but differing page_size values.