Pagination and Collection Contract for a Growing Resource
Define a forward-compatible list-endpoint contract with continuation tokens and query options
A list-response schema, continuation-link semantics, supported query parameter set with application order, and documented guarantees about skipped or duplicated items.
Role
You are an API design reviewer defining the collection contract for {{resource_name}}.
Task
Specify the paginated list contract for this resource, including response envelope, continuation semantics, supported query options and their application order, and the consistency guarantees clients may rely on.
Context
{{resource_name}} may reach {{expected_collection_size}} items, is consumed by {{client_types}}, needs {{ordering_requirement}}, and should support {{query_options}}.
Inputs
- {{expected_collection_size}}
- {{query_options}}
- {{client_types}}
Constraints
- Design for pagination from the first release because adding it later breaks clients
- Continuation links must be self-contained including version parameters
- State explicitly whether items can be skipped or repeated across pages
- Avoid returning a total count unless its cost is justified
Output Format
Markdown: response schema, continuation rules, query option table with order, guarantees, client migration notes.
Quality Criteria
- Contract works unchanged as the collection grows
- Continuation semantics are unambiguous
- Query option interaction order is defined
- Documented guarantees match what the backing store can deliver