Collection Pagination
Overview
Most collection resources need some kind of pagination. Without it, a simple search could return millions of records, bringing your network to a crawl. So, instead of receiving all the records of a collection resource, you can limit the number of records that are displayed on a page in the REST client response.
URL Format for Collection Resource Parameters
Pagination Request Parameters
To limit the number of records returned, set the following parameters in the request payload:
Request Parameters | Description |
---|---|
limit |
Used to specify the paging size, up to 1000. If no limit is specified or if a limit greater than 1000 is specified, a pagination limit of 1000 will be used. |
offset |
Used to specify the starting point from which the resources are returned. Notes:
|
totalResults |
Used to set to true to include the total number of search records that match the query. Notes:
|
Example Requests
-
To return records 11 through 30, append the following string to an applicable REST endpoint:
?offset=10&limit=20
-
To query for records where the
lastName
is 'Jones' and return records 1 through 10, append the following string to an applicable REST endpoint:?q=lastName LIKE 'Jones%'&limit=10
-
To query for records where the
lastName
is 'Jones' and return records 26 through 50, append the following string to an applicable REST endpoint:?q=lastName LIKE 'Jones%'&offset=25
-
To return records 1 through 20, and include the record count that matches the query, append the following string to an applicable REST endpoint:
?totalResults=true&limit=20
Pagination Response Parameters
The following pagination fields are returned in the response payload:
Request Parameters | Description |
---|---|
count |
The number of records included in the response. |
hasMore |
Indicates if there are more records to be returned from the collection.
|
totalResults |
The total number of records in the collection |
Example Responses
-
If the client runs a GET command on an accounts resource. The server stores 100 accounts and the current request returns only 25. To indicate that there are more records to retrieve, the server sets the read-only
hasMore
field to 'true'."items": [ ... ], "count": 25, "hasMore": true, "limit": 25, "offset": 0, "links": [ { ... } ] }
-
If you set the
totalResults
parameter to true in the request, the response includes thetotalResults
field to indicate the total number of records that match your search criteria. After retrieving all the records as indicated by thetotalResults
value, the server setshasMore
to 'false'.{ "items": [ ... ], "totalResults": 100, "count": 25, "hasMore": true, "limit": 25, "offset": 0, "links": [ { ... } ] }