Appearance
Pagination
Pagination consists in breaking down the list of returned objects into subsets that you can then navigate.
Treezor offers 2 methods to paginate API responses, depending on the endpoints.
| Method | Description |
|---|---|
| Offset-based | Divides the results into pages by indicating the number of items per page. |
| Cursor-based | Uses a cursor to mark the last item in each page. |
Offset-based pagination
Parameters
Endpoints supporting offset pagination rely on the following query parameters for pagination.
| Attribute | Description |
|---|---|
pageNumber | The number of the page to retrieve. |
pageCount | The number of objects per page. |
sortBy | The object attribute to sort the list with (e.g., creationDate, modifiedDate, etc.). Differs for each endpoint. |
sortOrder | The order you want to sort the list. Either:
|
Examples
Let's retrieve the list of transfers for a specific wallet with the following pagination parameters:
- 1st page (
pageNumber=1) - 30 objects (
pageCount=30) - Sorted by creation date (
sortBy=creationDate) - In chronological order, so that the most recently created is displayed last (
sortOrder=ASC)
You need to make the following request:
bash
curl -X GET {baseUrl}/v1/transfers?pageNumber=1&pageCount=30&sortBy=creationDate&sortOrder=ASC&walletId={{walletId}} \
--header 'Authorization: Bearer {accessToken}'1
2
2
Returns an array of 30 objects (or less, in the last page).
json
[
{
"walletId": 28749,
"createdDate": "2019-03-10T08:05:10-00:00",
[...]
},
{
"walletId": 92758,
"createdDate": "2020-08-25T07:08:20-00:00",
[...]
},
{
"walletId": 57820,
"createdDate": "2021-02-03T07:09:33-00:00",
[...]
},
[...] // 27 more objects hidden
]1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Now, let's retrieve the same list of transfers for the wallet, but with the following pagination parameters instead:
- 5th page (
pageNumber=5) - 50 objects (
pageCount=50) - Sorted by amount (
sortBy=amount) - In descending order, so that the highest amount is displayed first (
sortOrder=DESC)
You need to make the following request:
bash
curl -X GET {baseUrl}/v1/transfers?pageNumber=5&pageCount=50&sortBy=amount&sortOrder=DESC&walletId={{walletId}} \
--header 'Authorization: Bearer {accessToken}'1
2
2
Returns an array of 50 objects (or less, in the last page).
json
[
{
"walletId": 82749,
"amount": 4298,
[...]
},
{
"walletId": 10855,
"amount": 2310,
[...]
},
{
"walletId": 42187,
"amount": 150,
[...]
},
[...] // 47 more objects hidden
]1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
Supported endpoints
Usually, endpoints with a v1 prefix in their path and used to retrieve a list of objects support offset pagination.
List of endpoints supporting offset pagination
Cursor-based pagination
Cursor-based pagination works by returning a pointer to a specific item in the dataset. Then, you specify one of the returned cursors in your next request to navigate the datasets.
As opposed to offset pagination, cursor-based pagination is not optional. As soon as you make your request to retrieve your list of objects, the results will be paginated and the first page will be displayed by default.
The number of objects returned varies depending on each endpoint. Most endpoints returns 50 objects.
Cursor object
API Responses for endpoints supporting cursors will include the cursor object.
json
"cursor": {
"prev": null,
"current": "356a192b7913b04c54574d18c28d46e6395428ab",
"next": "da4b9237bacccdf19c0760cab7aec4a8359010b0"
}1
2
3
4
5
2
3
4
5
| Attribute | string | Description |
|---|---|---|
prev | string | Pointer for the previous page. null if on the first page. |
current | string | Pointer for the current page. |
next | string | Pointer for the next page. null if on the last page. |
If there is no adjacent operation, the next attribute will be valued to null. The current attribute can be cached and used later to only retrieve new operations.
Parameters
Endpoints supporting cursor-based pagination rely on the cursor query parameters for pagination. The size of the subset (number of objects returned) varies depending on each endpoint. Most endpoints returns 50 objects.
| Attribute | Description |
|---|---|
cursor | The desired starting position for your next subset of objects. |
Example
When initially using the {baseUrl}/core-connect/operations, the response returned 50 operations and included the cursor object.
json
"cursor": {
"prev": null,
"current": "356a192b7913b04c54574d18c28d46e6395428ab",
"next": "da4b9237bacccdf19c0760cab7aec4a8359010b0"
}1
2
3
4
5
2
3
4
5
Since there is no prev value, we know we are on the first subset of responses. To navigate to the next subset, the next value must be used for the cursor query parameter, as in the following request:
bash
curl -X GET {baseUrl}/core-connect/operations?walletId={walletId}&dateFrom={dateFrom}&dateTo={dateTo}&cursor=da4b9237bacccdf19c0760cab7aec4a8359010b0 \
--header 'Authorization: Bearer {accessToken}'1
2
2
This returns the next subset of Operations objects, which will include the cursor object again:
json
"cursor": {
"prev": "e99a18c428cb38d5f260853678922e03abd83395",
"current": "da4b9237bacccdf19c0760cab7aec4a8359010b0",
"next": null
}1
2
3
4
5
2
3
4
5
In this example, the next value is null, indicating that we are on the last subset.
Supported endpoints
Usually, endpoints with a core-connect prefix in their path and used to retrieve a list of objects support cursor-based pagination. Some v1 endpoints have been migrated to this pagination system too.