Listing children and pagination
This page is for app developers who build a list screen: the news of a folder, the products of a category. It
explains the list route of the REST API, how to page through it and how to sort it.
Contents
The route
GET /api/ezp/<version>/content/node/<id>/list(/offset/<n>)(/limit/<n>)(/sort/<key>(/asc|desc))Every part in brackets is optional, but the order is fixed: offset before limit, limit before sort. The route is
a regular expression (ezpList in rest_provider.php) and the controller's own comment says so: "you can't provide
sorting params before limit params". Defaults from the controller: offset 0, limit 10, sort order asc, and no
sort key (the order then follows the default of the content query).
curl -s -H "Authorization: Bearer $EXP_API_KEY" \
"https://example.com/api/ezp/v1/content/node/<node id>/list/offset/0/limit/20?ResponseGroups=Fields"This exact pattern is the call of an existing mobile app, recorded in the guide's comparison of answers before and after 6.0.15 (Activation combinations).
The answer
{
"childrenNodes": [
{"objectName": "...", "classIdentifier": "article", "datePublished": 0, "dateModified": 0,
"objectRemoteId": "...", "objectId": 0, "nodeId": 0, "nodeRemoteId": "...", "fullUrl": "https://example.com/...",
"link": "https://example.com/api/ezp/v1/content/node/<id>", "fields": {"...": "..."}},
"..."
],
"metadata": {"childrenCount": 0, "parentNodeId": "<id>"},
"requestedResponseGroups": ["Fields", "Metadata"]
}The values are placeholders; the keys are those of getChildrenList() and doList(). fields appears only with
ResponseGroups=Fields. link is the REST address of the child at the same version, with the request's
Translation and OutputFormat parameters.
Paging
metadata.childrenCount is the number of all children the query finds, not of this page. Loop like this:
offset = 0, limit = 20
repeat:
GET .../list/offset/{offset}/limit/{limit}
show childrenNodes
offset = offset + limit
until offset >= metadata.childrenCountFor infinite scroll, request the next page when the user nears the end of the loaded items, and stop when offset
reaches childrenCount. Offsets shift when editors publish or remove items between two requests; deduplicate by
nodeId in the app. The shipped configuration sets no maximum limit for this route; keep pages small (20 to 50) so
the first screen appears fast on mobile networks.
Sorting
.../list/offset/0/limit/20/sort/published/desc
.../list/limit/50/sort/nameThe sort key is passed to the content tree fetch as its SortBy value. The examples in the controller use name
and published; the node sort names used by the same fetch elsewhere in the code (the expservices list in
expcontentbase.php) are path, published, modified, section, depth, class_identifier, class_name,
priority, name, modified_subnode, node_id and contentobject_id. To follow the order editors chose in the
administration, sort by priority, or ask a remote service for the node's sort settings (expnode::sortInfo).
Counting
curl -s -H "Authorization: Bearer $EXP_API_KEY" https://example.com/api/ezp/v2/content/node/<node id>/childrenCountAnswers metadata with childrenCount and parentNodeId, for a badge or to size a list before loading it.
What the list leaves out
- Only direct children (depth 1). For a whole subtree use
expnode::subtreeof the remote services. - No class filter. Filter in the app, or use
expnode::childrenwith a filter, orexpnode::byClass(Calling expservices from an app). - Children the user may not read. A list checks
content/readof its parent, "the children are filtered by the fetch" (Permissions of the REST interface).
Related pages
- Response groups
- Caching in the app
- REST API v1 and v2: the routes
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.