Search API Design

Simple filtering (`?status=shipped`) and real search are different problems - search implies ranking by relevance, not just matching a boolean condition, and a well-designed search endpoint needs to expose that ranking behavior alongside the filters a client also wants to combine with it.

The `q` parameter carries the free-text query (matched by relevance ranking, not exact equality), while `category` and `price_max` are ordinary structured filters, narrowing the searchable set before or alongside ranking. Both can compose in the same request, and `sort=relevance` (the default for a search endpoint, unlike a plain listing endpoint which usually defaults to something like creation date) makes explicit that results are ranked, not just filtered.

Facets let a client build a filter sidebar without a separate request per possible filter value - the search response itself reports which categories, brands, or other dimensions actually appear (and how often) within the current result set, so the client can render "Electronics (340)" as a clickable refinement, computed against the live results rather than the whole catalog.

Highlighting wraps the matched query terms within the result (commonly with `<em>` tags or a similar marker) so a client can visually show the user why a given result matched, which matters most for fuzzy or partial matches where the connection between query and result isn't immediately obvious from the plain title alone.