# 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 allows 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
    }
  }
}