Pagination
How a list read is walked a page at a time: the page size a caller may ask for, the size the list answers when the caller names none, the cursor the answer hands back, and one loop that walks from the first page to the last.
How a page is read
A list read that takes a page answers one page at a time: the rows on this page, and beside them the cursor of the next page. The first read names no cursor; the walk starts there.
The answer's nextCursor field is null when the answer carries the last page. That is the only signal the walk is done, so a reader stops on it and never counts pages.
The limit
A list read answers 50 rows when the caller names no limit.
Whatever the caller asks for, one page never carries more than 200 rows.
A limit below 1 or above 200 is refused, so the list never answers more rows than one page may carry.
The calls that take a page, each linking its own page with its parameters and its answer:
GET /v1/registry/companies- Read the companies one registry holds
The cursor
The cursor is the page link the previous answer carried: take its nextCursor value and pass it back as cursor. It is opaque, so read it and change it never. A cursor longer than 512 characters is refused before it is read.
A cursor the list does not accept is refused in one of these sentences, and every one sends the reader back to the first page:
- A refused cursor
- This page link is longer than 512 characters, so it is not one this list gave out.
- A refused cursor
- This page link is damaged or incomplete, so it is not one this list gave out.
- A refused cursor
- This page link was made by another version of this list, so start again from the first page.
Walking every page
Pass the answer's nextCursor back as cursor to read the next page, and stop when it comes back null. A page the list answers with 429 is waited out: wait the seconds its Retry-After header names, capped at the longest wait the SDK holds, and ask again, up to three times. A 503 means the data source is not live yet, so it ends the walk at once with no wait. When a page cannot be read, the error carries the rows read so far, so a caller can resume from the last cursor.
async function walkEveryPage(baseUrl, headers) {
const rows = [];
let cursor = null;
do {
const url = new URL(baseUrl);
url.searchParams.set("limit", String(50));
if (cursor !== null) url.searchParams.set("cursor", cursor);
let response = await fetch(url, { headers });
for (let retries = 0; retries < 3 && response.status === 429; retries++) {
const seconds = Math.min(3600, Math.max(1, Number(response.headers.get("Retry-After")) || 1));
await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
response = await fetch(url, { headers });
}
if (!response.ok) {
const refused = new Error("the list read refused with " + response.status);
refused.rows = rows;
throw refused;
}
const page = await response.json();
rows.push(...page.items);
cursor = page.nextCursor;
} while (cursor !== null);
return rows;
}