Designing Search APIs

People do not always know the exact item they are looking for. A customer searching for “distributed systems” may have neither a book title nor an identifier in mind. The API needs to find useful candidates, explain enough of each result to support a choice, and preserve exact constraints such as language and format. A fast response is not useful if it quietly ignores a filter or exposes an unpublished book.

A search API defines how a query becomes a ranked set of discoverable resources.

This chapter covers query meaning, endpoint design, relevance, result representations, permissions, freshness, continuation, and failures using a fictional bookstore API over HTTPS.