Pagination

Table of Contents

• General
• Pagination
• Example
• Default & Maximum

---

General

In some cases, requests results in a very large amount of returned resources (e.g. orders, products, ...). To ensure quick result times and small network load, interfaces may return a list with resources and a way to navigate these lists.

💡 Please pay attention to the response pattern to identify how to handle lists.

There are two common ways list handling is implemented. One way is to retrieve the next entry of a list by using links for navigation the entries. The other is by provding list pages to iterate through lists.

Pagination

For pagination, the basic query parameter pageSize(e.g. ?pageSize=10) can be used to define the maximum amount of resulting entities returned per request. The interface itself can reduce the limit lower than you query parameter limit.

Example

"pagination": {
   "pageSize": 10,
   "pageIndex": 7,
   "totalPages": 22,
   "totalItems": 212,
   "self": "&pageSize=10&pageIndex=7",
   "first": "&pageSize=10&pageIndex=1",
   "prev": "&pageSize=10&pageIndex=6",
   "next": "&pageSize=10&pageIndex=8"
   "last": "&pageSize=10&pageIndex=22"
}

Estimated result count

⚠️ totalItems, totalPages and last are estimations and may be sometimes not 100% acurate. Qilin.Cloud is using this technique, to generate very fast pagination results (and therefore faster results at all when calling the APIs) by estimating the total count of results from the databases metadata, instead of actual count it. Especially when it comes to results with millions of objects (or tables that got trillions of rows), the estimation is magnitues faster.

For creating your exit condition when iterating through the results of an API, see totalItems, totalPages and last only as a guide (and maybe use it for some rough progressbar in your UI). It is advisable to set the exit condition so that the iteration only ends when no more data are returned from the next page.

Default & Maximum

You will find Qilin.Cloud default pageSize on this wiki page: Timeouts & Defaults

The maximum allowed value for pageSize is 500.