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.

GET/api/restaurants

Sort results by Description and Name fields.

RESTJavaScript

GET/api/restaurants

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

200 OK

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

GET/api/restaurants

Sort results by Description ascending and Name descending.

RESTJavaScript

GET/api/restaurants

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

200 OK

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

GET/api/articles

Return only 10 entries on page 1.

RESTJavaScript

GET/api/articles

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

200 OK

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

GET/api/articles

Return only the first 10 entries using offset.

RESTJavaScript

GET/api/articles

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

200 OK

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