You are setting the filtering grammar for a public API that many teams will extend over years, and clients keep asking for richer queries. How do you decide between a small fixed set of filter parameters and a general query language, and how do you leave room to evolve without a breaking change?

## Framing the decision The question is not "which syntax is nicer". It is: how much query surface am I willing to make permanent, and how much optionality can I keep while still serving clients today? Every filter capability you ship is a promise. Clients build on it, and in a public API you cannot see who. A bounded grammar makes small promises (these fields, these operators) that are individually removable-ish and collectively cheap to serve. A general query language makes one enormous promise: *arbitrary predicates over the declared model*. You cannot walk that back later, and its cost profile is set by the caller rather than by you. ## The case for starting bounded A field×operator matrix is: - **Validatable** — every request either matches the matrix or gets a `400`. - **Cost-bounded** — the worst possible query is a known, testable shape, so capacity planning is real rather than aspirational. - **Documentable and generatable** — one declaration produces docs, SDK methods, validation, and tests. - **Additive** — new fields and operators do not disturb existing clients. And it is usually sufficient: the overwhelming majority of real list queries are a conjunction of a few constraints plus a time range. ## When to graduate Adopt an expression language on evidence, and name the evidence you'd collect: - The rate and content of `400 unsupported filter` responses, aggregated by requested field/operator — this is your feature-request queue, already prioritized by demand. - Clients issuing N requests and unioning results client-side, which is an OR emulated in the wrong place (visible as bursts of near-identical calls from one key). - Clients pulling large pages and filtering locally — a sign that the server-side vocabulary is too poor, and a bandwidth and privacy problem too. - Repeated bespoke endpoints (`/orders/open-or-large`) accreting in the API — each one is an unmet grammar need frozen into a URL. If that evidence is broad, pick an existing standard rather than inventing syntax: RSQL/FIQL is compact and URL-friendly with off-the-shelf parsers; OData is far bigger but standardized end to end with real tooling. Inventing a grammar means owning a parser, a spec, and a decade of edge cases — occasionally right, rarely. ## Leaving room to evolve **Reserve syntax before you need it.** Declare up front that parameter names beginning with `$` (or a specific reserved `filter` parameter) belong to the API's control vocabulary and are not resource fields. Without this reservation, the day a resource gains a field called `filter` or `sort`, your control parameters and your data model collide, and both fixes are breaking. **Make the capability discoverable.** Publish the filter matrix as a machine-readable document (an endpoint, or annotations in the OpenAPI description). Clients then feature-detect instead of hardcoding, and you can add capabilities without a version bump. This is what makes "start small" safe: growth is observable to clients. **Version the capability, not the path.** Adding a filterable field or operator is additive; removing one is the breaking act. So run a deprecation process on the matrix — mark deprecated, measure usage per API key, notify, then remove — instead of minting `/v2` because the query vocabulary grew. **Keep a pressure valve.** `POST /resource/search` with a JSON query body handles queries that are too long for a URL, too nested for a query string, or too sensitive to appear in access logs and browser history. It costs GET cacheability and bookmarkability, which is exactly why it is the exception, not the default. Naming this tradeoff — and that a POSTed search is not idempotent-cacheable — is the mark of a considered answer. **Cap from day one, not after the incident.** If you do adopt a language: maximum AST depth, maximum terms, maximum distinct fields, a required selective predicate on large collections, per-query timeouts, and cost-aware quotas. Retrofitting caps onto clients who already write 40-term predicates is a breaking change you will not enjoy. ## The organizational half The grammar is a platform decision, not a service decision. If each team picks, you get four grammars, four validators, four sets of security bugs, and clients that must learn all of them. Write it into the API style guide, provide the shared library that implements the matrix, and make review of new filterable fields cheap — the friction you add is what keeps expensive fields from appearing quietly. Equally, plan the migration story: if a service already ships a different grammar, support both in parallel behind the discovery document, measure usage, and retire the old one on a published schedule, rather than declaring the standard and letting reality diverge from it. ## What separates a principal answer Not the syntax preference — the reasoning about permanence, evidence, and reversibility: start with the smaller promise, instrument demand so the decision to grow is data-driven, reserve the syntax that makes growth non-breaking, cap before the language ships, and treat the vocabulary as versioned contract owned by the platform rather than by whichever team needed a filter last quarter.