Agent WranglersLists
Page through long lists with cursors, cap every page, and let clients filter and sort with plain, documented parameters that never change meaning.
- Required 3
- Recommended 2
Required
Page lists with cursors
RequiredReturn long lists in pages, and point to the next page with an opaque cursor, not a page number.
Cap the page size
RequiredSet a default page size and a maximum. Clamp or reject anything above the maximum.
Return empty lists as empty
RequiredAnswer an empty result with 200 and an empty array. Never answer 404 or
nullfor a list with nothing in it.
Recommended
Filter with plain parameters
RecommendedLet clients filter lists by named query parameters, and document each one with its type.
Sort in a stable order
RecommendedSort every list in a documented, stable order, and let clients choose from a fixed set of sort keys.
For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers api design playbook: https://agentwranglers.se/playbook/api-design/lists.