Filtering Query Parameters
What you'll learn: How to design query parameters that let clients filter resource collections effectively without overcomplicating your API.
When clients request a collection of resources—like /api/products or /api/users—they rarely want every record. They need ways to narrow results: "show me only active users" or "find products under $50." Query parameters are your tool for this.
The Simple Approach: Equality Filters
The easiest pattern uses query parameters for exact matches:
GET /api/products?category=electronics&inStock=true
GET /api/users?role=admin&status=active
Each parameter filters by exact equality. This covers 80% of real-world needs and keeps your API intuitive. The server interprets category=electronics as "WHERE category = 'electronics'" in database terms.
When Simple Isn't Enough
Sometimes clients need more power: ranges, partial matches, or multiple values. You have options:
Comma-separated values:
GET /api/products?tags=organic,local
Range operators in parameter names:
GET /api/products?priceMin=10&priceMax=50
GET /api/events?startDate=2024-01-01&endDate=2024-12-31
Pattern matching conventions:
GET /api/users?name=John*
Avoid Over-Engineering
Complex query languages (like full SQL-in-URL or JSON-based filters) exist but add massive complexity. Reserve these for internal tools or power-user APIs. For public APIs, simple equality filters with occasional range parameters hit the sweet spot between power and usability.
Design Guidelines
- Document every supported filter parameter
- Use consistent naming (
status, notuserStatussometimes andproductStateelsewhere) - Return meaningful errors for unsupported filters
- Combine filtering naturally with pagination you learned earlier
Key Takeaway: Start with simple equality filters using query parameters; add range operators or multi-value support only when clear use cases demand it, avoiding complex query languages that sacrifice API usability.