Shaping a collection
A list endpoint becomes far more useful when callers can narrow and order it. Rather than a new endpoint per use case, expose query parameters on the collection.
Common parameter shapes
- Filtering: a field equals a value, like status equals active, narrows the set.
- Sorting: a sort parameter names a field and a direction, often a minus sign for descending.
- Field selection: a fields parameter lets the caller ask for a subset of attributes to shrink payloads.
- Searching: a free text query parameter for fuzzy matches.
Guardrails that matter
- Only allow filtering and sorting on indexed columns, or an attacker can force expensive scans.
- Apply a default and maximum page size so one request cannot read everything.
- Validate parameter names and reject unknown ones rather than silently ignoring them.
Treat filters, sort, and pagination as a small pipeline applied in order on the server.
Key idea
Expose filtering and sorting as query params, but restrict them to indexed fields and cap result size to protect the server.