Filtering & Sorting
On this page
Filtering and sorting are API UX
Good query design lets clients get exactly what they need without creating dozens of endpoints. The key is to keep it expressive but constrained.
Filtering patterns
Use query parameters for filters. Keep naming consistent across endpoints.
GET /api/orders?status=paid&customerId=42
Range filters
Pick a readable convention and stick to it. Two common patterns are “min/max” or operator suffixes.
GET /api/orders?createdAtFrom=2026-01-01&createdAtTo=2026-02-01 GET /api/products?priceMin=10&priceMax=50
Sorting
A simple convention: sort with field name, and prefix with - for descending.
GET /api/orders?sort=-createdAt GET /api/orders?sort=customerId,createdAt
Whitelist allowed fields
Do not allow arbitrary column names. Map allowed query fields to safe internal fields to prevent abuse and accidental data leaks.
Search
For free-text search, use a dedicated parameter and document expected behavior.
GET /api/users?q=ada
Common mistakes
- Letting clients filter by any database column
- Inconsistent parameter names between endpoints
- Sorting without stable tiebreakers (id)
Checklist
- Filtering parameters are consistent and documented.
- Sorting uses a stable convention and safe allow-list.
- Search has a clear scope and performance limits.