Filtering and Sorting

Filtering and sorting are essential features for any API that returns collections. Let's learn how to design these features effectively.

Filtering Basics

Simple Equality Filters

GET /api/products?category=electronics
GET /api/users?status=active
GET /api/orders?customerId=123

Multiple Filters (AND logic)

GET /api/products?category=electronics&inStock=true&brand=Apple

All conditions must be true.

Multiple Values (OR logic)

GET /api/products?status=pending,processing,shipped
# or
GET /api/products?status=pending&status=processing&status=shipped

Advanced Filtering

Range Filters

Use suffixes or operators for ranges:

# Suffix approach
GET /api/products?price_min=100&price_max=500
GET /api/users?created_after=2024-01-01

# Operator approach
GET /api/products?price[gte]=100&price[lte]=500
GET /api/products?price=gte:100,lte:500

Comparison Operators

Operator	Meaning	Example
eq	Equals	price[eq]=100
ne	Not equals	status[ne]=cancelled
gt	Greater than	age[gt]=21
gte	Greater or equal	price[gte]=100
lt	Less than	quantity[lt]=10
lte	Less or equal	rating[lte]=5
in	In list	status[in]=a,b,c

Null Checks

GET /api/users?manager=null        # No manager
GET /api/users?manager=!null       # Has manager

Sorting

Basic Sorting

GET /api/products?sort=price       # Ascending (default)
GET /api/products?sort=-price      # Descending (- prefix)

Multiple Sort Fields

GET /api/products?sort=category,-price
# Sort by category ascending, then price descending

Alternative Syntax

# Separate order parameter
GET /api/products?sort=price&order=desc

# Explicit direction
GET /api/products?sort=price:asc,name:desc

Exercise: Build Filter and Sort Logic

Best Practices

1. Document Filterable Fields

# OpenAPI
parameters:
  - name: status
    in: query
    schema:
      type: string
      enum: [active, pending, completed]

2. Validate Filter Values

// Bad request response for invalid filter
{
  "error": {
    "code": "INVALID_FILTER",
    "message": "Invalid value for 'status'. Must be: active, pending, completed"
  }
}

3. Set Reasonable Defaults

GET /api/products
# Defaults: sort by createdAt desc, limit 20

4. Limit Sortable Fields

Don't allow sorting by every field - only indexed ones.

Summary

Feature	Example
Simple filter	?category=books
Multiple values	?category=books,music
Range filter	?price_min=10&price_max=100
Sort ascending	?sort=name
Sort descending	?sort=-name
Multiple sort	?sort=category,-price