Lists and paging
Lists and paging
Lists answer a page at a time; the headers say where you are.
Example request
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
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:
| Name | Type | Description | Allowed values |
|---|---|---|---|
x-total-rows | header | How many rows there are in all. | — |
x-page-number | header | This page’s number. | — |
x-page-size | header | How many rows a page holds, after any clamp. | — |
x-next-cursor | header | On 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
limitabove 100 is read as 100;x-page-sizesays 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
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.
Type a call, a field or a guide.