Pagination
Every collection but one comes back a page at a time, in a fixed envelope, in a deterministic order.
Parameters
Query parameters
| Parameter | Type | Description |
|---|---|---|
| page | integer | Which page to return. Counting starts at 1. A page past the end returns no rows rather than an error, and the envelope still says how many pages there are. |
| per_page | integer | How many rows a page holds. The default is 25 and the maximum is 100; anything larger is capped rather than refused. |
The envelope
A paged reply is a data array and a meta object. meta is what you page on, so you never have to guess when you have reached the end.
{
"data": [
"…"
],
"meta": {
"page": 1,
"per_page": 25,
"count": 412,
"pages": 17
}
}
Order is deterministic. Listings and tags are sorted by name and then by id, so paging through a whole directory cannot hand you one row twice and skip another.
Categories are not paged
The categories index returns the whole tree, in tree order, with a meta object carrying count and no page fields. Tree order is computed rather than sorted, so there is no offset to apply; a directory's tree is tens of rows and is capped at five levels deep. Do not write a paging loop for it — there is no second page to fetch.