Search Is a Different Contract Than Filtering

GET /products?category=shoes&color=blue and GET /search?q=blue+running+shoes both return product lists, and everything else about them differs. The filter is a predicate: membership is boolean, the result set is exact and complete, two identical requests against unchanged data return identical sets, and "no results" means the subset is empty — a fact. The search is an intent: matching is graded (typo tolerance, stemming, synonyms), the result is a *ranking* in which relevance below some threshold simply stops being shown, and "no results" often means the query and the index missed each other — a retrieval failure, not a fact about the world.

The contract consequences are concrete. A filter result can feed a reconciliation job; a search result must never, because completeness was never promised. A filter's ordering is whatever Sorting: Determinism or Drift says; a search's default ordering *is the product* — relevance — and offering ?sort=price on search results is a real decision (users want it) with a real cost (it discards the ranking that made the results good, so it usually applies after a relevance cutoff, and the docs should say so). Even the empty state differs: an empty filter result renders "no orders match"; an empty search result renders "did you mean…", spelling suggestions, and a relaxed re-query — affordances the API can only support if it returns the machinery for them.

This is why mature APIs keep the surfaces separate: /orders?status=… for predicates, /search?q=… (often POST, for long queries) for intent — frequently backed by different engines entirely, because the primary database's B-trees answer predicates and an inverted index answers text relevance. Bolting LIKE '%blue%' onto the filter endpoint delivers the worst of both: unindexable leading-wildcard scans, no ranking, no typo tolerance — filtering's cost with none of search's value.

Search pagination inherits every problem from Pagination: Choosing How Lists End and adds two of its own. First, scores are not stable keys: the index updates continuously and rankings shift between requests, so page 2 computed a minute after page 1 may be a page of a *different* ranking — items repeat or vanish across the boundary, offset-drift by another mechanism (see Offset Pagination: Simple, Jumpable, and Lying Under Writes). Engines answer with a traversal that pins state: a scroll/search-context token — morally a Cursor Pagination: An Opaque Bookmark, Not a Position cursor whose anchor is a ranking snapshot rather than a keyset. Such contexts hold server resources, so they carry lifetimes ("valid 5 minutes") and the contract must say what expiry returns.

Second, depth is not worth what it costs. Serving page 200 of a ranked result means scoring and merging the top 10,000 candidates to discard 9,950 — top-k cost grows with k, across every shard. Meanwhile no human uses it: search click-through is overwhelmingly page one. So mature search APIs cap depth explicitly — Elasticsearch defaults to 10,000 results; Google stops around 400 — and the cap is a *contract feature*: it prices the endpoint honestly and tells the consumer who wants everything that they want an export or a filtered traversal instead, not deep search. Return totals in the same honest spirit: "about 12,400" (bounded estimate) rather than an exact count you would have to fully execute the query to know.

The same honesty applies to what a result *is*. Search responses returning full records tie index shape to response models and bloat pages; returning ids forces an N+1 hydration round trip. The usual contract is a search hit: id, type, a display projection (title, snippet with match highlighting), and optionally the score — with the record itself fetched from the system of record when the user commits. This also keeps authorization coherent: results must be permission-filtered *before* ranking and counting, because "3 results (2 hidden)" leaks existence — the search index needs the permission model, which is one of the quiet costs of running one (see Authorization Design in the Contract).

A search API commits you to a pipeline, not a query: analysis choices (tokenization, stemming, synonyms — language-specific), an indexing path that consumes every write (with the lag that implies — a user who renames a document and searches for the new name *will* file the bug the freshness clause exists to answer), relevance tuning that is never finished, and increasingly a hybrid of lexical and semantic retrieval, where embeddings catch "sneakers" for "running shoes" and an inverted index catches exact part numbers that embeddings fumble. Each capability is a differentiator and a permanent operational commitment; the contract's job is to expose *capabilities* ("typo-tolerant", "searches title and body") without freezing *implementation* (the analyzer, the engine, the formula) into promises.

That seam matters most for ranking. Consumers will ask how scoring works; answer in kind — "relevance considers text match, recency and popularity" — and explicitly reserve the right to improve it, because a frozen formula is a frozen product (and an invitation to adversarial optimization by anyone ranked). Keep score values documented as non-comparable across queries and releases. Autocomplete deserves its own contract for the same reason: per-keystroke traffic at 10–50x search volume, a few-ms latency budget, tiny responses, aggressive caching — a different endpoint with different limits, not search with limit=5 (see The Rate-Limit Contract).