Course contentsShow
← System Design
Lesson 1892 of 1,91945. API Design and VersioningFree lesson

Filtering Query Parameters

Designing filter syntax for field-based queries, supporting operators like equals, greater-than, and contains.

Filtering Query Parameters

What you'll learn: How to design a flexible, URL-based filtering syntax that lets API clients query resources by specific field values and conditions.

Why Filtering Matters

After implementing pagination to handle large result sets, the next challenge is letting clients narrow down what data they actually want. Filtering allows users to request only resources matching certain criteria—think "show me all products under $50" or "find users in New York with admin status."

Core Design Principles

Design your filter syntax using query parameters that map to resource fields. The basic pattern is:

GET /api/products?category=electronics&price_lt=100

Each parameter specifies a field and optionally an operator. Common approaches:

Operator Encoding

Suffix notation (popular, readable):

  • ?price_lt=100 → price less than 100
  • ?name_contains=phone → name contains "phone"
  • ?status_eq=active → status equals active (or just ?status=active as default)

Bracket notation (more structured):

  • ?price[lt]=100
  • ?name[contains]=phone

Standard Operators

  • Equality: field=value or field_eq=value
  • Comparison: _gt, _gte, _lt, _lte (greater/less than)
  • Pattern matching: _contains, _startswith, _endswith
  • Set membership: _in=val1,val2,val3

Multiple Filters

Combine filters with &:

GET /api/users?role=admin&created_after=2024-01-01&country=US

Filters are typically combined with AND logic by default. For OR logic, you may need special syntax like ?status_in=active,pending.

Key Takeaway:
A well-designed filter syntax uses query parameters with explicit or suffix-encoded operators (like _lt, _contains) to let clients precisely select resources based on field values, making APIs flexible and self-documenting.