Search⌘ K
AI Features
Home
Courses
Grokking the Product Architecture Interview

API Model for Search Service

Explore how to model a search API to meet key functional requirements, including endpoint definitions, HTTP methods, and data structures for client-server communication. Understand private API interactions with recommendation and ads services, plus error handling for a scalable search system.

We'll cover the following...

In this lesson, we model the search API to meet the functional requirements we identified in the first lesson. We also focus on essential data entities to be exchanged in the request and response while targeting various endpoints.

Let's start the discussion by defining the base URL for our search API.

Base URL and API endpoints

The base URL can be defined as the common prefix for all the endpoints of API. We defined the following base URL for the search API:

The base URL for search API
The base URL for search API

The following illustration represents the URLs and their HTTP methods used by the search service.

The search API operations and their corresponding endpoints

The details of query string parameters that we mentioned in the URLs above are given below:

  • Search: The search keywords are passed as a query parameter along with the base URL.

  • Sort: The order defines the sequence of the records (such as descending or ascending). Additionally, the sort parameter sorts the results based on the field provided in the query parameter—for example, sort by the price or date field.

  • Pagination: This endpoint takes various parameters based on the type of pagination we aim to perform. For example, using the bucket pattern requires a skip parameter in the query.

The message format for API endpoints

This section presents data entities, requests, and response structures for the messages exchanged between client and server to meet different functional requirements. Let’s start our discussion with the data entities required, as given below.

Search data entities

Data entities are the key-value pairs sent in the request and response messages between the client and endpoints to exchange data. We have listed the data entities we considered essential for our API. In reality, they can greatly vary in number based on the features the service offers.

YAML
type search 
{
    query: string            \\ This is the search term entered by the user
    sort: string             \\ This is a name of field that needs to be sorted
    order: string            \\ The sequence of results e.g. ascending or descending order
    count: integer           \\ This represents the total number of results
    pageNumber: integer 
    limit: integer           \\ The maximum number of results displayed on a page
    results: list            
    recommendations: list    
    adsSuggestions: list     
    partialResponse: boolean \\ This flags the response to be partial due to processing timeout
}

The search query

The search query is sent through the URL in a call to the search API. We divide the search query into multiple parts as explained below:

  • HTTP method: Since we aim to retrieve data based on a query string, the GET method is a suitable choice. The GET request doesn't carry the body, so the search query is sent in the URL.

1.

Can we use the POST method to request a search query?

Show Answer
Did you find this helpful?
  • Request format: We’ve mentioned some essential headers, such as HOST, X-API-KEY, Accept, and so on. The Accept header indicates that the client can accept data only in the JSON format. For authentication, we define API keys in the custom header, which is X-API-KEY. Also, the GET method has no body, and all the required data entities are added to the URL as parameters.
HTTP format
cURL format
GET /v1.0/search/query={string} HTTP/1.1
HOST: api.search.com 
Accept: application/json
X-API-KEY: "API Key"
//other headers
The HTTP request format for search query

Note: If the request contains user credentials by passing the Authorization: Bearer <JWT> header, the search will return personalized ads, recommendations, and results.

  • Response format: The response header will contain some necessary information, like Content-Type, whereas the response body could contain multiple data entities, such as results, pageNumber, and so on.
Scala
HTTP/1.1 200 OK
Content-Type: application/json
//other headers
{
   "query":  "Java Courses",
   "pageNumber": 1, 
   "count": 10,
   "results": [...]
}

Recommendation service

The recommendation service is only accessible internally, and its API calls are private to the organization. To understand the interaction between the API gateway and the recommendation service, we’ll discuss the request-response model of these calls here.

  • HTTP method: Since we need to fetch the recommendations based on the search query and user's query history, the GET method is the obvious choice.

  • Request format: The following request format is used to get recommendations.

HTTP format
cURL format
GET /v1.0/recommendations/query={string} HTTP/1.1
HOST: api.search.com 
Accept: application/json
X-API-KEY: "API Key"
//other headers
The HTTP request format for recommendations

  • Response format: If the request is successfully executed, the list of recommendations in the response body is given below. The querytitle represents the title of the suggested query, and link represents the link of the suggested query.

Scala
HTTP/1.1 200 OK
Content-Type: application/json
//other headers
{
   "recommendations": {
         { "id": 1, "querytitle": "value", "link" : "value"},
         { "id": 2, "querytitle": "value", "link" : "value"},
         { "id": 3, "querytitle": "value", "link" : "value"},
         { "id": 4, "querytitle": "value", "link" : "value"},
         { "id": 5, "querytitle": "value", "link" : "value"},
    }
}

Ads service

The ads service is also a private API whose calls are limited to the organization's internal use. Let's look at the request-response structure below to understand the interaction between the API gateway and the ads service.

  • HTTP method: The GET method is used to fetch the advertisements from the ads service.

  • Request format: The request format for the ads service is given below.

HTTP format
cURL format
GET /v1.0/ads/query={string} HTTP/1.1
HOST: api.search.com 
Accept: application/json
X-API-KEY: "API Key"
//other headers
The HTTP request format for ads

  • Response format: The response format includes a list of advertisements, as given below.

Scala
HTTP/1.1 200 OK
Content-Type: application/json
//other headers
{
    "adsSuggestions": {
         { "id": 1, "title": "value", "image" : "link" ....},
         { "id": 2, "title": "value", "image" : "link" ...},
}

Failed requests

The common errors that the API may return in response to a request are listed in the following table.

Error Responses

Status Code

Phrase

Description

400

Bad Request

When a request is missing parameters or missing headers

401

Unauthorized

Provided access token is invalid

403

Forbidden

The server listens to the request but does not fulfill it

404

Not Found

Requested query is invalid

429

Too Many Requests

Too many requests are sent in a specific time period

500

Server Error

Indicates problem on the server side

Summary

We familiarized ourselves with the API endpoints for different functionalities and understood the request and response structure of the messages exchanged between the client and server. The following table provides a summary of what we have learned so far.

Operations

Endpoints

Data Entities

Response

(Status Code, Body)

Search

GET /v1.0/search?query={string}

Parameters are passed in the URL

200 OK, Yes

Sort

GET /v1.0/searchquery={string}&sort={field}&order={ascending}

Parameters are passed in the URL

200 OK, Yes

Pagination

GET /v1.0/search?query={string}&skip={value}&limit={value}

Parameters are passed in the URL

200 OK, Yes

Recommendation

GET /v1.0/recommendations/query={string}

Parameters are passed in the URL

200 OK, Yes

Advertisement

GET /v1.0/ads/query={string}

Parameters are passed in the URL

200 OK, Yes