Search API Design
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
GET /products/search?q=wireless+headphones&category=electronics&price_max=200&sort=relevanceThe 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
{
"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
{
"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.
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.
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.
No comments yet. Be the first to start the thread!