REST APIs in Depth · Representations, Collections and Queries
Filtering, Sorting and Search
Query parameter conventions, operators, allow-lists and when to use a search endpoint.
Keep simple filters as query parameters (?status=paid&created_after=2026-01-01), support multiple values consistently (?status=paid,shipped or repeated params), and use a documented sort syntax (?sort=-created_at,total). Allow-list filterable and sortable fields and back them with indexes. For complex queries (boolean logic, full-text, facets), expose a dedicated search resource (GET /orders/search?q=… or POST /orders:search with a JSON body when the query is too large for a URL) backed by a search engine.
Filtering conventions
| Need | Approach | Example |
|---|---|---|
| Exact match | Query param | ?status=paid |
| Multiple values | CSV or repeated | ?status=paid,shipped |
| Ranges | Suffixed params | ?created_after=…&created_before=… |
| Sorting | sort with - prefix | ?sort=-created_at,id |
| Free text | q param → search engine | ?q=blue mug |
| Complex boolean filters | Search resource with JSON body | POST /orders:search {filter:{…}} |
Common pitfalls
- Letting clients filter/sort on unindexed or sensitive fields.
- Building SQL from raw filter strings (injection).
- A custom mini query language nobody documents.
Key points
- Simple, documented conventions
- Allow-list fields; index them
- Dedicated search resource for complex queries
Further reading: Google AIP-160: Filtering
Practice questions
When is POST acceptable for a read-only search?
Answer
When the query is too large or complex for a URL (long filter trees), or contains sensitive data that shouldn't appear in URLs/logs. Model it as a search resource and keep it free of side effects.
Why allow-list sortable fields?
Answer
Sorting by arbitrary fields can bypass indexes (slow full scans), expose hidden fields, and enable injection if field names are interpolated into SQL.
Open in the app to mark lessons complete, take notes and track your progress.