# 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
(opens new window) 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
.
# 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 fieldGET /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 request: Sort using 2 fields
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": {
// ...
}
}
JavaScript query (built with the qs library):
qs
(opens new window) can be used to build the query URL used in the example above:
const qs = require('qs');
const query = qs.stringify({
sort: ['title', 'slug'],
}, {
encodeValuesOnly: true, // prettify URL
});
await request(`/api/articles?${query}`);
Example request: Sort using 2 fields and set the order
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": {
// ...
}
}
JavaScript query (built with the qs library):
qs
(opens new window) can be used to build the query URL used in the example above:
const qs = require('qs');
const query = qs.stringify({
sort: ['title:asc', 'slug:desc'],
}, {
encodeValuesOnly: true, // prettify URL
});
await request(`/api/articles?${query}`);
# 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
Example response
{
"data": [
// ...
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 10,
"pageCount": 5,
"total": 48
}
}
}
JavaScript query (built with the qs library):
qs
(opens new window) can be used to build the query URL used in the example above:
const qs = require('qs');
const query = qs.stringify({
pagination: {
page: 1,
pageSize: 10,
},
}, {
encodeValuesOnly: true, // prettify URL
});
await request(`/api/articles?${query}`);
# 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
Example response
{
"data": [
// ...
],
"meta": {
"pagination": {
"start": 0,
"limit": 10,
"total": 42
}
}
}
JavaScript query (built with the qs library):
qs
(opens new window) can be used to build the query URL used in the example above:
const qs = require('qs');
const query = qs.stringify({
pagination: {
start: 0,
limit: 10,
},
}, {
encodeValuesOnly: true, // prettify URL
});
await request(`/api/articles?${query}`);