This is necessary when a large number of items need to be returned (usually videos), since to reduce bandwidth the API only returns a subset of the available results. Each subset is returned in a page. If there are more items in the result set than would fit within a single page, multiple pages will need to be requested to return the entire result set.
The first page (the default if none is specified) is page zero (since the index starts at 0, in common with most programming). That number is then incremented to move to the next page.
The pagination values are passed in the URL’s query string. In general the following variables can be used:
| Variable | Description |
|---|---|
| page | (int) The number of the page e.g. 1 |
| perPage | (int) The number of results per page e.g. 10 |
| sortBy | (string) The field to sort by e.g. createdtime |
| sortDirection | (string) The direction to sort by e.g. desc |
When a set of results is returned, there are different ways you can check to see if another request needs to be made:
1) You can count the number of results. If you requested, say, 10 items per page and only 5 have been returned clearly there won’t be another page of results following that one.
2) You can check whether the ‘nextPage’ key is a URL. Each API response that returns multiple results includes a ‘prevPage’ and ‘nextPage’ key. These can either be null or a URL to that page of results.
The exception to both cases is when the number of results happens to match the number requested per page. For example if you ask for 10 items per page, and 10 are returned, there is not enough information to know whether there is an 11th item and so whether there is another page of results. Therefore the ‘nextPage’ attribute will be set in case. Upon requesting the next page, it is at that point that you will know, since the result set will then be empty, and the ‘nextPage’ attribute will be null accordingly.
The other limitation to be aware of is that since our video API is stateless, the number of items may change between requests for separate pages (for example if a new user happens to be created at the very moment you are requesting multiple pages of users). This is unlikely, but possible (as with most other APIs) since the result set is not cached and as such is retrieved as an independent request each time.
To find out more about our business video hosting (including access to the API), please use our contact form or you can email us at [email protected].
Updated: December 23, 2015