REST API pagination and sorting

API pagination and sorting

List endpoints (/api/trees, /api/facts, etc.) support pagination and sorting to handle large datasets efficiently.

Pagination parameters

• limit – Number of items per page. Default: 50, maximum: 200.
• offset – Number of items to skip. Default: 0.
• page – Alternative to offset: page number (1‑indexed). Example: page=3&limit=20 returns items 41‑60.

Response headers for pagination

Responses include headers to help navigate pagination:

• X-Total-Count – Total number of items (across all pages).
• X-Limit – Items per page (same as requested limit).
• X-Offset – Current offset.
• Link – RFC 5988 links for first, prev, next, last.

Sorting parameters

• sort – Field to sort by. Options: createdAt, updatedAt, title (trees), subject (facts). Default: updatedAt.
• order – asc (ascending) or desc (descending). Default: desc.

Example request

GET /api/trees?limit=20&offset=40&sort=title&order=asc

Returns trees 41‑60, sorted alphabetically by title.