REST API: Sort & Pagination

Entries that are returned by queries to the REST API can be sorted and paginated.

Tip

Strapi takes advantage of the ability of the qs library to parse nested objects to create more complex queries.

Use qs directly to generate complex queries instead of creating them manually. Examples in this documentation showcase how you can use qs.

You can also use the interactive query builder if you prefer playing with our online tool instead of generating queries with qs on your machine.

Sorting

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

• GET /api/:pluralApiId?sort=value to sort on 1 field
• GET /api/:pluralApiId?sort[0]=value1&sort[1]=value2 to sort on multiple fields (e.g. on 2 fields)

The sorting order can be defined with:

• :asc for ascending order (default order, can be omitted)
• or :desc for descending order.

Example: Sort using 2 fields

You can sort by multiple fields by passing fields in a sort array.

Example request: Sort using 2 fields

GET /api/restaurants?sort[0]=Description&sort[1]=Name

JavaScript query (built with the qs library):

The query URL above was built using the qs library. qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  sort: ['Description', 'Name'],
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);

Example response

{
  "data": [
    {
      "id": 9,
      "documentId": "hgv1vny5cebq2l3czil1rpb3",
      "Name": "BMK Paris Bamako",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "A very short description goes here."
            }
          ]
        }
      ],
      // …
    },
    {
      "id": 8,
      "documentId": "flzc8qrarj19ee0luix8knxn",
      "Name": "Restaurant D",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "A very short description goes here."
            }
          ]
        }
      ],
      // …
    },
   // … 
  ],
  "meta": {
    // …
  }
}

Example: Sort using 2 fields and set the order

Using the sort parameter and defining :asc or :desc on sorted fields, you can get results sorted in a particular order.

Example request: Sort using 2 fields and set the order

GET /api/restaurants?sort[0]=Description:asc&sort[1]=Name:desc

JavaScript query (built with the qs library):

The query URL above was built using the qs library. qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

const qs = require('qs');
const query = qs.stringify({
  sort: ['Description:asc', 'Name:desc'],
}, {
  encodeValuesOnly: true, // prettify URL
});

await request(`/api/restaurants?${query}`);

Example response

{
  "data": [
    {
      "id": 8,
      "documentId": "flzc8qrarj19ee0luix8knxn",
      "Name": "Restaurant D",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "A very short description goes here."
            }
          ]
        }
      ],
      // …
    },
    {
      "id": 9,
      "documentId": "hgv1vny5cebq2l3czil1rpb3",
      "Name": "BMK Paris Bamako",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "A very short description goes here."
            }
          ]
        }
      ],
      // …
    },
    // …
  ],
  "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: Return only 10 entries on page 1

GET /api/articles?pagination[page]=1&pagination[pageSize]=10

JavaScript query (built with the qs library):

The query URL above was built using the qs library. qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

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

await request(`/api/articles?${query}`);

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: Return only the first 10 entries using offset

GET /api/articles?pagination[start]=0&pagination[limit]=10

JavaScript query (built with the qs library):

The query URL above was built using the qs library. qs can be run locally on your machine, as shown in the following code example, or you can use our interactive query builder online tool.

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

await request(`/api/articles?${query}`);

Example response

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