Course contentsShow
← Software Engineering
Lesson 787 of 1,93324. REST API DesignFree lesson

Filtering Query Parameters

Designing filter parameters for resource collections, choosing between simple equality filters and complex query languages.

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, not userStatus sometimes and productState elsewhere)
  • 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.