Lists and paging

Lists and paging

Lists answer a page at a time; the headers say where you are.

Example request

The second page of 50bash
curl -i "https://console.brevily.com/api/NORTHWIND/links?limit=50&page=2" \  -H "x-api-key: brv_ak_7Fq2Lw9xK3" \  -H "x-api-secret: $BREVILY_SECRET"

Example answer

Where you arehttp
HTTP/1.1 200 OKx-total-rows: 112x-page-number: 2x-page-size: 50[ …50 links… ]

Made-up values.

A list answers a plain JSON array, one page of it: 25 rows unless you ask for up to 100 with ?limit=, and the next page with ?page= (the first is 1). The same two can travel as the x-page-number and x-page-size headers; the query wins when both are sent. Where you are comes back as headers:

Paging headers
NameTypeDescriptionAllowed values
x-total-rowsheaderHow many rows there are in all.—
x-page-numberheaderThis page’s number.—
x-page-sizeheaderHow many rows a page holds, after any clamp.—
x-next-cursorheaderOn a list kept by time, instead of the three above: the next page’s cursor, absent on the last page.Send it back as ?before=

The lists that page: list the organisation’s links, list domains and list the organisation’s tags.

What is clampedPermalink

  • A limit above 100 is read as 100; x-page-size says what you got.
  • A page number above 1,000 is read as 1,000, so a walk reaches the first 100,000 rows.
  • A value that is not a whole number above 0 (0, -1, abc) is ignored: the default stands. Nothing about paging is ever refused.
  • A page past the end answers an empty array, with the headers as ever.

Reading every pagePermalink

Every link, a page at a timejavascript
async function allLinks() {  const links = [];  for (let page = 1; ; page++) {    const res = await fetch(      `https://console.brevily.com/api/NORTHWIND/links?limit=100&page=${page}`,      { headers: { 'x-api-key': KEY_ID, 'x-api-secret': SECRET } },    );    const rows = await res.json();    links.push(...rows);    const total = Number(res.headers.get('x-total-rows'));    if (rows.length === 0 || links.length >= total) return links;  }}

Common mistakesPermalink

  • Asking for more than 100 and reading the answer as all of them. Read x-total-rows, or walk the pages.
  • Starting at page 0: it is ignored, so the first page comes back, and a loop counting from 0 reads it twice.
  • Expecting a wrapper object: a list is the array itself; its count and position are in the headers.
  • Walking pages while the list changes: a row added or removed meanwhile shifts the rows after it, so one can be read twice or missed. Compare the total at the end with the start.