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