Your list endpoint forwards query-string filter parameters into the data layer, and clients may name any field and any operator. What goes wrong in production, and how do you constrain the surface without crippling the API?

## Why passthrough filtering is a real incident class "Whatever the client sends, we pass to the query builder" is convenient and appears in a lot of internal APIs. It fails in three distinct ways. ### 1. Information exposure A filter is a *predicate oracle*. Even if the field never appears in the response body, being able to filter on it lets a caller binary-search values: `?internal_risk_score[gt]=90` returns the high-risk customers, and repeated queries recover a per-record value one bit at a time. Fields the API deliberately hides — internal scores, moderation flags, soft-delete markers, other tenants' identifiers — must not be filterable either. Filter names also leak schema. Error messages like "unknown column `users.password_reset_token`" hand an attacker a map. Whitelist errors should name only fields *from the whitelist*, never echo the storage layer's message. The worst variant is **silent ignore**. A client scopes a list with `?owner_id=42`; the server does not recognize the parameter and drops it; the response contains every owner's data. It looks like a UX nit and behaves like a broken-access-control incident. Fail closed: unknown filter → `400`. ### 2. Attacker-controlled cost With arbitrary filters, the caller chooses your query plan. `?notes[contains]=a` over a hundred million rows, or a filter on a column with no index, converts a millisecond endpoint into a scan that saturates the database for everyone. Rate limiting by request count does not help, because the requests are few and each is enormous. This is the practical reason to distinguish, inside the whitelist, which fields are *cheap* (indexed, selective) and which are *expensive* (free-text, computed, joined). Mitigations, in layers: mark each filterable field as indexed or not; require at least one indexed/selective predicate (or a bounded time range) on large collections; cap the number of filter terms per request; enforce a statement timeout so a bad query dies rather than piles up; run heavy list traffic on a read replica; and monitor list-endpoint latency **by filter shape**, not just by route, so one pathological shape is visible instead of averaged away. ### 3. Injection Parameterization protects *values*, not identifiers. A field name or an operator concatenated into a query string is an injection point in SQL, and in document stores the equivalent is passing a client-supplied operator object straight into the query — the classic NoSQL operator injection where a value of `{"$ne": null}` turns an equality check into "anything". The defense is not escaping: it is mapping. The client's `created_at` looks up a server-owned column reference; the client's `gte` looks up a server-owned operator. Anything not in the map never reaches the query layer. ## The whitelist as an artifact Make it a declaration, per resource, not scattered `if` statements: - field name (public name, mapped to internal column/path) - allowed operators for that field - value type and constraints (enum members, max string length, allowed date range) - cost class (indexed / unindexed / joined / computed) - whether the field requires a particular authorization From that single declaration you generate validation, the query translation, the documentation, the `400` error's `supported` block, and tests. Anything not declared is unsupported — which also means adding a filter is a deliberate, reviewable contract change rather than something that appears because a column was added. ## Authorization interacts with filtering Filtering must be applied *on top of* the caller's authorized scope, never as a substitute for it. The server-side tenant/owner predicate is appended unconditionally, independent of the query string; the client's filters can only narrow further. And note the corollary: a filter on a field the caller may not read should be rejected, because narrowing by an invisible field still reveals it. ## Values, not just fields Coerce by declared type before use: a date field gets a parsed date, an enum field gets a member check, a numeric field a range check. Bound list-valued operators (`status[in]=` with 10 000 members is a cost attack) and bound string lengths for `contains`. Reject with `400` and a specific, safe message. ## What not to do Don't try to make everything filterable "for flexibility" and defend it with a query cost analyzer you haven't built. Don't accept raw predicate fragments (`?where=`) under any framing. Don't rely on the client SDK to restrict what is sent. And don't respond to abuse by removing filters clients already depend on — that is why the matrix should be treated as public contract with a deprecation path from the start. ## Strong answer, compressed "Filtering is a declared capability, not a passthrough. Per resource I declare field → operators → type → cost class; unknown field or operator is a 400 naming it, never a silent drop, because a dropped scoping filter returns everyone's rows. Values are coerced and bounded. Expensive fields are marked, large collections require a selective predicate, statement timeouts and per-filter-shape latency metrics catch the rest. Authorization scope is appended server-side regardless of what the client filters on."