Pagination
APIs that can return multiple (e.g. thousands) records support retrieving a block or page of records. This pagination policy has two key concepts:
- page number - identifies a block (page) of records, starting with page number 1. The page number is defined using the optional pageNumber query parameter and its default value is 1;
If the pageNumber is 0, negative or non-numeric - 400 Bad Request will be returned.
- page size - identifies the number of records for a given page. The page size is defined using the optional pageSize query parameter and its default value is 100. pageSize cannot exceed 1000;
If the pageSize is negative, non-numeric or exceeds the maximum value - 400 Bad Request will be returned.
The response body of APIs supporting pagination includes total property. The total property is the object’s total number of records.
The following table contains example page number and page size values and the range of records retrieved.
Examples
| pageNumber | pageSize | Records returned |
|---|---|---|
| foo | 1 | 400 Bad Request |
| -1 | 1 | 400 Bad Request |
| 0 | 1 | 400 Bad Request |
| 1 | foo | 400 Bad Request |
| 1 | -1 | 400 Bad Request |
| 1 | 1001 | 400 Bad Request |
| 1 | 0 | Empty result but contains total |
| 1 | 10 | 1-10 |
| 2 | 10 | 11-20 |
| 3 | 10 | 21-30 |
| 1 | 100 | 1-100 |
| 2 | 100 | 101-200 |
| 3 | 100 | 201-300 |
| 1 | 1,000 | 1-1,000 |
| 2 | 1,000 | 1,101-2,000 |
| 3 | 1,000 | 2,001-3,000 |
Updated over 2 years ago