REST API: Sort & Pagination

The REST API by default does not populate any relations, media fields, components, or dynamic zones. It will return all fields for the model and while populating.

Sorting

Queries can accept a sort parameter that allow sorting on one or multiple fields with the following syntax:

Sort using 2 fields

Example request

const qs = require('qs');
const query = qs.stringify({
  sort: ['title', 'slug'],
}, {
  encodeValuesOnly: true,
});

await request(`/api/articles?${query}`);
// GET /api/articles?sort[0]=title&sort[1]=slug

Example response

{
  "data": [
    {
      "id": 1,
      "attributes": {
        "title": "Test Article",
        "slug": "test-article",
        // ...
      }
    },
    {
      "id": 2,
      "attributes": {
        "title": "Test Article",
        "slug": "test-article-1",
        // ...
      }
    }
  ],
  "meta": {
    // ...
  }
}

Sort using 2 fields and set the order

The sorting order can be defined with :asc (ascending order, default, can be omitted) or :desc (for descending order).

Example request

const qs = require('qs');
const query = qs.stringify({
  sort: ['title:asc', 'slug:desc'],
}, {
  encodeValuesOnly: true,
});

await request(`/api/articles?${query}`);
// GET /api/articles?sort[0]=title%3Aasc&sort[1]=slug%3Adesc

Example response

{
  "data": [
    {
      "id": 2,
      "attributes": {
        "title": "Test Article",
        "slug": "test-article-1",
        // ...
      }
    },
    {
      "id": 1,
      "attributes": {
        "title": "Test Article",
        "slug": "test-article",
        // ...
      }
    }
  ],
  "meta": {
    // ...
  }
}

Pagination

Queries can accept pagination parameters. Results can be paginated:

• either by page (i.e. specifying a page number and the number of entries per page)
• or by offset (i.e. specifying how many entries to skip and to return)

✏️ NOTE

Pagination methods can not be mixed. Always use either page with pageSize or start with limit.

Pagination by page

To paginate results by page, use the following parameters:

Parameter	Type	Description	Default
pagination[page]	Integer	Page number	1
pagination[pageSize]	Integer	Page size	25
pagination[withCount]	Boolean	Adds the total numbers of entries and the number of pages to the response	True

Example request: Select only 10 entries on page 1

const qs = require('qs');
const query = qs.stringify({
  pagination: {
    page: 1,
    pageSize: 10,
  },
}, {
  encodeValuesOnly: true,
});

await request(`/api/articles?${query}`);
// GET /api/articles?pagination[page]=1&pagination[pageSize]=10

Example response

{
  "data": [
    // ...
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 10,
      "pageCount": 5,
      "total": 48
    }
  }
}

Pagination by offset

To paginate results by offset, use the following parameters:

Parameter	Type	Description	Default
pagination[start]	Integer	Start value (i.e. first entry to return)	0
pagination[limit]	Integer	Number of entries to return	25
pagination[withCount]	Boolean	Toggles displaying the total number of entries to the response	true

💡 TIP

The default and maximum values for pagination[limit] can be configured in the ./config/api.js file with the api.rest.defaultLimit and api.rest.maxLimit keys.

Example request

const qs = require('qs');
const query = qs.stringify({
  pagination: {
    start: 0,
    limit: 10,
  },
}, {
  encodeValuesOnly: true,
});

await request(`/api/articles?${query}`);
// GET /api/articles?pagination[start]=0&pagination[limit]=10

Example response

{
  "data": [
    // ...
  ],
  "meta": {
    "pagination": {
      "start": 0,
      "limit": 10,
      "total": 42
    }
  }
}