Pagination/Continuation
Pagination (sometimes called “continuation”) allows lists of items to be retrieved in subsets called “pages”. APIs that support the retrieval of large quantities of resources MUST implement pagination. APIs that return relatively small-sized lists (e.g. a list of days of the week) MAY choose not to.
Pagination Types
Section titled “Pagination Types”Trimble APIs use either offset-based pagination or cursor-based pagination.
Offset-Based Pagination
Section titled “Offset-Based Pagination”Most APIs that return collections allow the caller to get a specific page of results. This is accomplished by including the URL parameter “pageIndex” in the request.
Subsequent pages of results from these APIs may be retrieved by forming URLs with an incrementing pageIndex value in the URL or by performing a GET to the URL for next returned in the links block.
APIs implementing offset-based pagination MUST support the following query parameters on collection requests that support a GET operation:
| Field | Purpose | Default | Notes |
|---|---|---|---|
| pageIndex | Identifies the index of the requested page. This is essentially the “page number” with the numbering starting at 0. | 0 (first page) | Zero-based integer. Optional. |
| pageSize | The largest quantity of items to be returned in a single response (in a single page). | 100 | Integer. Optional. If 0, the API returns an empty items[] array. This is used, for example, when a caller simply wants to know the number of items in a collection that is returned in the metadata of the response. APIs MUST NOT return less than this quantity of items unless it is the last page. |
Example:
GET https://api.trimble.com/service/things?pageIndex=3&pageSize=20With the default behavior,
GET https://api.trimble.com/service/thingswill return the same result as:
GET https://api.trimble.com/service/things?pageIndex=0&pageSize=100APIs that use offset-based pagination MUST return an array of items along with metadata that contains the page index (zero-based), the total quantity of items in the entire result set and links to get the next page, etc. as follows:
| Field | Description | Notes | Required |
|---|---|---|---|
| pageIndex | index of the returned page | Integer | Required |
| totalItems | total number of items in the entire query result, across all pages | Integer | Required |
| items | The data items returned in this specific page | JSON array of JSON objects. If a query results in no items, this is an empty JSON array. | Required |
| links | See Common Pagination Information and Contract below. | Required |
Cursor-Based Pagination
Section titled “Cursor-Based Pagination”APIs implementing cursor-based pagination do not accept any parameters regarding specific pages. The initial call always returns the first page of results.
Subsequent pages of results from these APIs may be retrieved by performing a GET to the URL for “next” returned in the “links” block.
APIs Implementing cursor-based pagination MUST have data that enable a stable sort to ensure consistent responses to queries.
APIs implementing cursor-based pagination MUST support the following query parameters on collection requests supporting a GET operation:
| Field | Purpose | Default | Notes |
|---|---|---|---|
| pageSize | The largest quantity of items to be returned in a single response (in a single page). | 100 | Integer. Optional. Note this can be 0 in which case the API returns an empty items[] array. This is used, for example, when a caller simply wants to know the quantity of items in a collection which is returned in the metadata of the response. Note that APIs MUST NOT return less than this quantity of items unless it is the last page. |
Common Pagination/Continuation Information & Contract (Both Paging Types)
Section titled “Common Pagination/Continuation Information & Contract (Both Paging Types)”Both paging types (offset and cursor) share and MUST include a common response block, links, that contains URLs that can be used to retrieve next and previous pages (and several other navigation URLs). The following are the navigation URLs supported, with the conditions in which they are required:
| Field | Purpose | Notes |
|---|---|---|
| self | A URL that will retrieve the response that was just received. | Required. This URL may not exactly match the URL provided by the caller but will return the same result. |
| first | A URL that will retrieve the first page of results. | Required. There is always a first page - even if it is empty. |
| next | A URL that will retrieve the next page of results. | Required if there is a next page. Omitted if no pages follow this page. |
| prev | A URL that will retrieve the previous page of results. | Required if there is a previous page. Omitted if no pages precede this page. |
| last | A URL that will retrieve the last page of results. | Required if there is a known last page. Omitted if the “last page” is unknown or too complex to calculate (as in a very rapidly growing collection) |
The URLs in the links block should not be parsed by client-side developers as their content and/or format may change without notice. These URLs are intended to be used in GET calls as-is without interpretation or modification.