REST API: Sort & Pagination
Entries that are returned by queries to theREST API can be sorted and paginated.
Strapi takes advantage of the ability ofthe `qs` library to parse nested objects to create more complex queries.
Useqs directly to generate complex queries instead of creating them manually. Examples in this documentation showcase how you can useqs.
You can also use theinteractive query builder if you prefer playing with our online tool instead of generating queries withqs on your machine.
Sorting
Queries can accept asort parameter that allows sorting on one or multiple fields with the following syntaxes:
GET /api/:pluralApiId?sort=valueto sort on 1 fieldGET /api/:pluralApiId?sort[0]=value1&sort[1]=value2to sort on multiple fields (e.g. on 2 fields)
The sorting order can be defined with:
:ascfor ascending order (default order, can be omitted)- or
:descfor descending order.
Example: Sort using 2 fields
You can sort by multiple fields by passing fields in asort array.
GET /api/restaurants?sort[0]=Description&sort[1]=Name
JavaScript query (built with the qs library):
The query URL above was built usingthe `qs` library.qs can be run locally on your machine, as shown in the following code example, or you can use ourinteractive query builder online tool.
const qs=require('qs');
const query= qs.stringify({
sort:['Description','Name'],
},{
encodeValuesOnly:true,// prettify URL
});
awaitrequest(`/api/restaurants?${query}`);
{
"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 thesort parameter and defining:asc or:desc on sorted fields, you can get results sorted in a particular 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 usingthe `qs` library.qs can be run locally on your machine, as shown in the following code example, or you can use ourinteractive query builder online tool.
const qs=require('qs');
const query= qs.stringify({
sort:['Description:asc','Name:desc'],
},{
encodeValuesOnly:true,// prettify URL
});
awaitrequest(`/api/restaurants?${query}`);
{
"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 acceptpagination parameters. Results can be paginated:
- either bypage (i.e., specifying a page number and the number of entries per page)
- or byoffset (i.e., specifying how many entries to skip and to return)
Pagination methods can not be mixed. Always use eitherpage withpageSizeorstart withlimit.
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?pagination[page]=1&pagination[pageSize]=10
JavaScript query (built with the qs library):
The query URL above was built usingthe `qs` library.qs can be run locally on your machine, as shown in the following code example, or you can use ourinteractive query builder online tool.
const qs=require('qs');
const query= qs.stringify({
pagination:{
page:1,
pageSize:10,
},
},{
encodeValuesOnly:true,// prettify URL
});
awaitrequest(`/api/articles?${query}`);
{
"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 |
The default and maximum values forpagination[limit] can beconfigured in the./config/api.js file with theapi.rest.defaultLimit andapi.rest.maxLimit keys.
GET /api/articles?pagination[start]=0&pagination[limit]=10
JavaScript query (built with the qs library):
The query URL above was built usingthe `qs` library.qs can be run locally on your machine, as shown in the following code example, or you can use ourinteractive query builder online tool.
const qs=require('qs');
const query= qs.stringify({
pagination:{
start:0,
limit:10,
},
},{
encodeValuesOnly:true,// prettify URL
});
awaitrequest(`/api/articles?${query}`);
{
"data":[
// ...
],
"meta":{
"pagination":{
"start":0,
"limit":10,
"total":42
}
}
}