11436 SSO

API Design: Scrutinizing Search Results and Links

May 17, 2013

Last time we talked about resource response messages. Here, we’ll turn our API design focus towards understanding how to represent search results and links in response messages.

To begin, Facebook’s API documentation states that, “Selecting results is not the same as searching.” This is exemplified when we create a language string and query box to search across resource types, whereas when we limit a selection to a specific collection (like photos), you give up the idea of saying give me everything about <something>.

Comparing search result responses

Let’s take a look at how three APIs approach represent search results in a response: Bing, Google Custom Search, and Reddit.

It gets overwhelming quickly, even without drilling down into the response metadata, when you are deciding what to include and what to leave out in a search response.

We recommend following Google custom search.

 "meta": {
   "limit": 1,
   "offset": 10,
   "totalResults": 15000000,
   "query": "sushi",
   "searchTime": 0.314942
 "results": [

Google includes metadata under a couple of different nested objects, including a limit and offset for pagination, the total results available, a query string that initiated the event, and (to show off) the search time. The results property includes an array of results returned.

Links are message cues that point to another resource.

If you survey the Netflix API, they use Web Linking. Link relation (rel) values may contain standard or custom relation identifiers, and include an href based on these rel values. Let’s consider how Netflix and GitHub represent links in the response.

Netflix API

  title="Elijah Wood”

GitHub API

"organization": {
  "login": "octocat",
  "id": 1,
  "url": "https://api.github.com/users/octocat",
  "type": "Organization”

In the Netflix API, notice that the href points to a URL with the rel value (person.actor) that refers to a title value (Elijah Wood). GibHub’s API repositories contain an organization object with a URL that houses a particular resource. Note, GitHub follows the Web Linking spec for some links and includes a link header with prev and next links.

We prefer Netflix’s use of Web Linking style, which can be expressed in both XML and JSON, since it adheres to a standard.  You can also utilize standard link relations where appropriate.

What are the heuristics for including links in your API responses?

Links help developers look at a response message and see a relationship, let’s say between a film and an actor, which allows them to continue their intuitive exploration of the API.

Templates are another alternative where, instead of returning a link, you return an ID that the developer plugs in. So if I saw people, I could do a GET on /people and plug in the ID (100637) at the end (/people/100637). That takes some context switching and coding structures to couple properly. By including the link in the response, the developer spends less time outside of your API with external documentation, which is important because we all know that context switching has a big cost.

To join the conversation around APIs, check out the API-Craft Google Group.

Next: Representing Actions and Metadata in Responses

Scaling Microservices