In this section · 6 articles

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

ParameterUseDefault
pageThe page number, from 1.1
per_pageHow 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:

JSON
{
  "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.

  • count is the number of records on this page. total and last_page are left out by endpoints that don't count the whole list.
  • A link that doesn't apply, such as prev on the first page, is left out.
  • The links keep your other parameters, such as filters. To read everything, follow links.next until 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

Plain text
?filter[country_id]=101
?filter[iso_code]=IN

Each 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

Plain text
?q=bang

q matches any of the endpoint's searchable fields, such as a city's name in any language your Laramin has.

Sorting

Plain text
?sort=name
?sort=-created_at
?sort=name,-created_at

A - 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

Plain text
?fields=id,name

Keeps 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.

Bash
# 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

JavaScript
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'
);