Implementing Filtering
1. Using Query Parameters for Filtering
| Pattern | Example |
|---|---|
| Equality | ?status=active |
| Multi-value (OR) | ?status=active,pending |
| Negation | ?status!=cancelled |
| Existence | ?email=* or ?has=email |
2. Implementing Multi-Field Filtering
| Logic | Convention |
|---|---|
| AND (default) | Multiple distinct params |
| OR within field | CSV: status=paid,shipped |
| Complex (nested) | RSQL/FIQL or POST search endpoint |
3. Implementing Comparison Operators
| Operator | Bracket Style | Suffix Style |
|---|---|---|
| Equal | price[eq]=100 | price=100 |
| Not equal | price[ne]=100 | price__ne=100 |
| Greater than | price[gt]=100 | price__gt=100 |
| GTE | price[gte]=100 | price__gte=100 |
| Less than | price[lt]=100 | price__lt=100 |
| LTE | price[lte]=100 | price__lte=100 |
| In | id[in]=1,2,3 | id__in=1,2,3 |
| Like | name[like]=%alice% | name__like=alice |
4. Implementing Full-Text Search
| Param | Use |
|---|---|
q | Universal search query |
search | Verbose alternative |
| Engines | PostgreSQL FTS, Elasticsearch, Meilisearch, Algolia |
5. Implementing Fuzzy Search
| Technique | Use |
|---|---|
| Levenshtein distance | Typo tolerance |
| Trigrams (pg_trgm) | Similarity matching in PostgreSQL |
| Phonetic (Soundex) | "Smith" / "Smyth" |
Elasticsearch fuzziness:AUTO | Built-in fuzzy matching |
6. Using Arrays in Filters
| Style | Example |
|---|---|
| CSV | ?tags=red,blue,green |
| Repeated key | ?tag=red&tag=blue |
| Bracket notation | ?tags[]=red&tags[]=blue |
7. Implementing Date Range Filtering
Example: Date Range
GET /orders?createdAt[gte]=2026-01-01&createdAt[lt]=2026-02-01
GET /orders?createdFrom=2026-01-01&createdTo=2026-02-018. Implementing Nested Field Filtering
| Pattern | Example |
|---|---|
| Dot notation | ?address.city=NYC |
| Bracket | ?address[city]=NYC |
| Underscore | ?address_city=NYC |
9. Handling Special Characters in Filters
| Character | Encoded |
|---|---|
| Comma in value | Use bracket array or URL-encode %2C |
| Ampersand | %26 |
| Equals | %3D |
| Spaces | %20 or + |
10. Implementing Filter Validation
| Check | Action |
|---|---|
| Unknown field | 400 Bad Request |
| Invalid value type | 400 + which field |
| Operator not supported on field | 400 with allowed list |
| SQL injection patterns | Use ORM/parameterized queries |
11. Documenting Filter Options
| OpenAPI Element | Documents |
|---|---|
parameters | Each filter param with type/enum |
x-filterable-fields | Custom extension for dynamic fields |
| Examples | Show common queries in description |