Learn about the different pagination approaches used by Wristband APIs.
Wristband APIs implement pagination to divide large datasets into smaller, manageable subsets. Two pagination methods are supported: offset pagination and cursor pagination. The following sections provide a detailed description of each.
Offset Pagination
Offset pagination supports traversing through ordered data sets by allowing you to specify an offset (the number of items to skip) and a size (the number of items to return per page).
Setting the Offset
Use the start_index
query parameter to set the offset. It is 1-based, meaning counting starts at 1. For example, start_index=1
returns the first item, while start_index=2
skips the first item and starts from the second.
Setting the Page Size
Use the count
query parameter to specify the number of items that should be returned per page. For example, count=10
means each page will contain at most 10 items.
Sorting Results
The sort_by
query parameter specifies the order of the paginated results. Its value must follow the syntax below:
<sort_attribute>[:(asc|desc)],...
For example, if we wanted to call the Query Tenant Users API, and sort the results by the user's family name in descending order, we would set the sort_by
query parameter to the following:
sort_by=familyName:desc
The attributes that can be used in the sort_by
query parameter depend on the API. Refer to the Sort Attributes section in the API documentation for the list of supported attributes.
A few additional things to note about sorting results:
- If multiple sort attributes are specified, attributes listed earlier have higher priority. For example,
sort_by=familyName:asc,givenName:desc
sorts byfamilyName
first, then bygivenName
. - If the sort order (
asc
ordesc
) is not specified, it defaults toasc
. For example,sort_by=familyName
is equivalent tosort_by=familyName:asc
Offset Pagination Response Body
Below is a table listing the fields that will be included in an offset pagination response.
Name | Type | Description |
---|---|---|
totalResults | Integer | The total number of items that exist across all pages. |
startIndex | Integer | 1-based index of the first result in the current page. |
itemsPerPage | Integer | The total number of items per page. |
items | List | List of items. The first item in the list will be the item at the offset specified by the startIndex . The size of the list will be no bigger than itemsPerPage . |
Example Request
To help illustrate how offset pagination works, let's look at an example request to the Query Application Users API:
Note
When using the
fields
query parameter, you don’t need to includeitems
in path expressions. Fields are matched directly against the entities in the items list
GET https://yourapp-yourorg.us.wristband.dev/api/v1/applications/app123/users?start_index=1&count=2&sort_by=givenName:asc&fields=id,givenName
In this case, the response might look like the following:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"totalResults": 4,
"startIndex": 1,
"itemsPerPage": 2,
"items": [
{
"id": "x25rpgafgvgedcvjw52ooul3xm",
"givenName": "Alice"
},
{
"id": "4a47jcm2ejayovsgbgbpkihblu",
"givenName": "Bill"
}
]
}
In the response, totalResults
is 4, indicating there are four users in application app123
. However, because count
is set to 2, only the first two users appear in the items list. To retrieve the remaining two users, repeat the request with start_index=3
:
GET https://yourapp-yourorg.us.wristband.dev/api/v1/applications/app123/users?start_index=3&count=2&sort_by=givenName:asc&fields=id,givenName
Now the returned results would contain the remaining two users:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"totalResults": 4,
"startIndex": 3,
"itemsPerPage": 2,
"items": [
{
"id": "47jcm2ejayovsgbgbpkihblu4a",
"givenName": "Chris"
},
{
"id": "hblu4a47jcm2ejayovsgbgbpki",
"givenName": "Dan"
}
]
}
Cursor Pagination
Cursor pagination supports traversing through ordered data sets by providing a cursor (pointer) to a specific item in the data set. The cursor can then be used to navigate to the next or previous page.
Navigating Pages Using Cursors
For APIs that support cursor pagination, the response body may include two cursor values, depending on whether previous or next pages exist:
pageBeforeCursor
- A cursor for navigating to the previous page. Present only if a previous page exists.pageAfterCursor
- A cursor for navigating to the next page. Present only if a next page exists.
Navigating to the Next Page
To retrieve the next page, use the pageAfterCursor
value from the response as the page_after
query parameter in your request. For example, if you were calling the Fetch Tenants API and got a response like the following:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"pageAfterCursor": "dGVzdDIsczJuNHhtYmFyYmJwZmxpYWFvYm9pdWV5djQ",
"items": [
{
"tenantId": "pl4a4aa4jzydksmrf3jnu5yfcw",
...
}
]
}
To go to the next page, you would take the value from the pageAfterCursor
and construct a request like the following:
GET https://yourapp-yourorg.us.wristband.dev/api/v1/tenant-discovery/fetch-tenants?count=10&page_after=dGVzdDIsczJuNHhtYmFyYmJwZmxpYWFvYm9pdWV5djQ
You can repeat this process until pageAfterCursor
is undefined, indicating that you've reached the last page.
Navigating to the Previous Page
To retrieve the previous page, use the pageBeforeCursor
value from the response as the page_before
query parameter in your request. For example, if you were calling the Fetch Tenants API and got a response like the following:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"pageBeforeCursor": "dGVzdDIsczJuNHhtYmFyYmJwZmxpYWFvYm9pdWV5djQ",
"items": [
{
"tenantId": "pl4a4aa4jzydksmrf3jnu5yfcw",
...
}
]
}
To go to the previous page, you would take the value from the pageBeforeCursor
and construct a request like the following:
GET https://yourapp-yourorg.us.wristband.dev/api/v1/tenant-discovery/fetch-tenants?count=10&page_before=dGVzdDIsczJuNHhtYmFyYmJwZmxpYWFvYm9pdWV5djQ
You can repeat this process until pageBeforeCursor
is undefined, indicating that you've reached the first page.
Setting the Page Size
Use the count
query parameter to specify the number of items that should be returned per page. For example, count=10
means each page will contain at most 10 items.