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.
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).
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.