Skip to content
API Design Learn/Production REST II: Correctness & Scale
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Search API Design

3 min read

You'll learn to

  • -Tell search (ranked by relevance) from filtering (a yes-or-no match)
  • -Combine a free-text q with structured filters in one request, and return facets
  • -Highlight the matched words and decide when search deserves its own endpoint

Filtering such as ?status=shipped and real search are different problems. A filter asks yes or no: does this item match? Search asks how well. It ranks results by relevance, meaning how closely each one fits what was typed. A good search endpoint exposes that ranking and lets clients combine it with the filters they also want.

An Analogy: The Librarian and the Shelf Label

A shelf label that says "Cookery" is a filter: a book is either on that shelf or not. Asking a librarian for "something quick with chicken" is search: she weighs the books and hands you the best fits first, and perhaps mentions "there are twelve more in Baking, if you like". That last remark is a facet.

Combining Full-Text Query With Facets

Free-text search combined with structured filters
GET /products/search?q=wireless+headphones&category=electronics&price_max=200&sort=relevance

The q parameter carries the free-text query, matched by relevance and not by exact equality. category and price_max are ordinary structured filters. They compose in one request. Search defaults to sort=relevance, unlike a plain listing that usually defaults to something like creation date, which makes it explicit that results are ranked and not merely filtered.

Faceted Results

Facets tell the client what other filters are available given the current results
{
  "results": [ /* matching products */ ],
  "facets": {
    "category": [{"value": "electronics", "count": 340}, {"value": "accessories", "count": 89}],
    "brand": [{"value": "Sony", "count": 52}, {"value": "Bose", "count": 41}]
  },
  "total_results": 429
}

Facets let a client build a filter sidebar without a request per possible value. The search response itself reports which categories, brands and other dimensions appear in the current results, and how often, so the client can show "Electronics (340)" as a clickable refinement computed against the live result set, not the whole catalog.

Highlighting Matched Terms

Showing the client exactly what matched, and why
{
  "id": 501,
  "name": "Sony Wireless Noise-Cancelling <em>Headphones</em>",
  "highlight": {"description": "...premium <em>wireless</em> audio experience..."}
}

Highlighting wraps the matched words in a marker, commonly <em>, so the client can show why a result matched. That matters most for fuzzy or partial matches where the link between query and result is not obvious from the title alone. The demo is a miniature of all three ideas. It scores four products for "wireless headphones", filters to electronics under $200, and prints the facets and highlighted names.

Press Run: ranked results, facets over the live matches, and highlighted names

A search endpoint is often best as its own route (/products/search) rather than a ?q= on the plain collection. That tells clients and infrastructure, such as caches and rate limiters, that it has different performance characteristics and meaning from a plain filtered list.

Interview Signal is part of Pro

See a real weak answer next to a real strong one for this exact topic.

Quiz is part of Pro

Test what you just read with a short quiz, and bank the XP.

Ready to Build This?

Design Search Engine API in the API Design Lab's Production Patterns act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!