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