Pagination

Overview

Certain APIs that could return a large amount of data are paginated using cursors. The SDK uses the cursor pattern (as opposed to pages) to better protect against changing data while paginating through a list of items. For more information on pagination strategies refer to this article.

Paginated results include the following properties:

• items: the list of items on the current request, defaulted to 100 items.
• nextCursor: the cursor to use for the next batch of items. This is undefined if there are no more items to fetch.
• hasMore: a boolean indicating if there are more items to fetch. This is false if there are no more items to fetch.
• totalItems: the total number of items available. This may change as new items are added to the list, only use this for informational purposes.
• sortBy: the field used to sort the items, by default this is startTimestamp.
• sortOrder: the order used to sort the items, by default this is desc.

To request all the items in a list, you can iterate through the list using the nextCursor until hasMore is false.

let hasMore = true;
let cursor: string | undefined;
const gateaways = [];
while (hasMore) {
  const page = await ario.getGateways({ limit: 100, cursor });
  gateaways.push(...items);
  cursor = page.nextCursor;
  hasMore = page.hasMore;
}

Filtering

Paginated APIs also support filtering by providing a filters parameter. Filters can be applied to any field in the response. When multiple keys are provided, they are treated as AND conditions (all conditions must match). When multiple values are provided for a single key (as an array), they are treated as OR conditions (any value can match).

Example:

const records = await ario.getArNSRecords({
  filters: {
    type: 'lease',
    processId: [
      'ZkgLfyHALs5koxzojpcsEFAKA8fbpzP7l-tbM7wmQNM',
      'r61rbOjyXx3u644nGl9bkwLWlWmArMEzQgxBo2R-Vu0',
    ],
  },
});

In the example above, the query will return ArNS records where:

• The type is "lease" AND
• The processId is EITHER "ZkgLfyHALs5koxzojpcsEFAKA8fbpzP7l-tbM7wmQNM" OR "r61rbOjyXx3u644nGl9bkwLWlWmArMEzQgxBo2R-Vu0"