Paging, filtering, sorting and caching
The query parameters Laramin's list endpoints share (page, per_page, filter, sort, q and fields), the paging details every list answer carries, and how to use ETags to avoid downloading what hasn't changed.
- Applies to
- Core 12.7 and later
- Who can do this
- Developer
On this page
Most list endpoints share the conventions below. Each endpoint decides which filters and sorts it allows, and some modules use their own parameters instead: Headless CMS's delivery API, for example, refuses filter and fields. Each endpoint's reference page says what it accepts.
Paging
| Parameter | Use | Default |
|---|---|---|
page | The page number, from 1. | 1 |
per_page | How many records per page, from 1 up to the endpoint's maximum. page[size] does the same. | Usually 15, up to 100. Some endpoints differ: notifications default to 20, up to 50. |
A value over the maximum is lowered to it, not refused.
A paged answer adds the paging details to meta, and a links object:
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
{
"success": true,
"message": "Success",
"data": [ { "id": 1, "name": "Afghanistan" }, { "id": 2, "name": "Albania" } ],
"meta": {
"request_id": "6f1d0c2e-…",
"locale": "en",
"current_page": 1,
"per_page": 2,
"count": 2,
"last_page": 125,
"total": 250
},
"links": {
"self": "https://crm.example.com/api/v1/public/reference/countries?page=1",
"first": "https://crm.example.com/api/v1/public/reference/countries?page=1",
"next": "https://crm.example.com/api/v1/public/reference/countries?page=2",
"last": "https://crm.example.com/api/v1/public/reference/countries?page=125"
}
}Replace the highlighted values with your own.
countis the number of records on this page.totalandlast_pageare left out by endpoints that don't count the whole list.- A link that doesn't apply, such as
prevon the first page, is left out. - The links keep your other parameters, such as filters. To read everything, follow
links.nextuntil it's missing.
Some endpoints page with a cursor instead, for long or fast-changing lists. Their meta has per_page, next_cursor and prev_cursor, and links has next and prev. Pass the cursor back as ?cursor=.
Filtering
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
?filter[country_id]=101
?filter[iso_code]=INEach endpoint lists the filters it allows. A filter it doesn't allow is refused with 400 and BAD_REQUEST, so a typo doesn't quietly return everything.
Searching
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
?q=bangq matches any of the endpoint's searchable fields, such as a city's name in any language your Laramin has.
Sorting
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
?sort=name
?sort=-created_at
?sort=name,-created_atA - sorts from highest to lowest. Separate several sorts with commas. A sort the endpoint doesn't allow is refused with 400. Without sort, the endpoint's own order applies.
Choosing fields
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
?fields=id,nameKeeps only the named keys in each record of data, to make answers smaller. It applies to the top level of each record, and to every endpoint that uses the standard envelope. An unknown name is ignored.
Language
Send X-Locale or Accept-Language to get translated names and messages in a language your Laramin has. meta.locale and the Content-Language header say which language you got.
Caching
Public read endpoints send an ETag and Cache-Control: private, max-age=60. An endpoint can set a different max-age. Keep the ETag, and send it back next time as If-None-Match. If nothing has changed, the answer is 304 Not Modified with no body, which is quicker and smaller.
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
# First request: note the ETag header
curl -i https://crm.example.com/api/v1/public/reference/currencies -H "Accept: application/json"
# Later: send it back
curl -i https://crm.example.com/api/v1/public/reference/currencies \
-H "Accept: application/json" \
-H 'If-None-Match: "3f1c9b27e09a"'Example: read every page
Couldn't copy. Select the code and press Ctrl+C (⌘+C on a Mac).
async function readAll(url, headers = {}) {
const records = [];
let next = url;
while (next) {
const res = await fetch(next, { headers: { Accept: 'application/json', ...headers } });
const body = await res.json();
if (!body.success) throw new Error(`${body.error.code}: ${body.message}`);
records.push(...body.data);
next = body.links?.next;
}
return records;
}
const states = await readAll(
'https://crm.example.com/api/v1/public/reference/states?filter[country_id]=101&per_page=100'
);Thanks. That helps us decide what to write next.
Thanks for telling us what was missing.
You already answered for this article today. Thanks.
We got a lot of answers from your network just now. Try again in a few minutes.
We couldn't send that. Check your connection and try again.
Links in this article
Printed from help.bsscn.com. The online article may have changed since.