Goophr Librarian is the actual maintainer of the index for a set of documents, and its responsibilities are to add terms to the index and to return query results for the search terms based on the terms available in the index.

Informally, we can define the API as follows:

• /api/index: Goophr Concierge calls this API endpoint to add terms to the actual index
  • The POST request adds terms to index
• /api/query: Goophr Concierge calls this endpoint to query search terms submitted by the user
  • The POST request returns results for search terms

The following is the OpenAPI definition for Goophr Librarian:

# openapi/librarian.yaml

openapi: 3.0.0
servers: 
  - url: /api 
info: 
  title: Goophr Librarian API 
  version: '1.0' 
  description: | 
    API responsible for indexing & communicating with Goophr Concierge. 
paths: 
  /index: 
    post: 
      description: | 
        Add terms to index. 
      responses: 
        '200': 
          description: | 
            Terms were successfully added to the index. 
        '400': 
          description: > 
            Request was not processed because payload was incomplete or 
            incorrect. 
          content: 
            application/json: 
              schema: 
                $ref: '#/components/schemas/error' 
      requestBody: 
        content: 
          application/json: 
            schema: 
              $ref: '#/components/schemas/terms' 
        description: | 
          List of terms to be added to the index. 
        required: true 
  /query: 
    post: 
      description: | 
        Search for all terms in the payload. 
      responses: 
        '200': 
          description: | 
            Returns a list of all the terms along with their frequency, 
            documents the terms appear in and link to the said documents. 
          content: 
            application/json: 
              schema: 
                $ref: '#/components/schemas/results' 
        '400': 
          description: > 
            Request was not processed because payload was incomplete or 
            incorrect. 
          content: 
            application/json: 
              schema: 
                $ref: '#/components/schemas/error' 
    parameters: [] 
components: 
  schemas: 
    error: 
      type: object 
      properties: 
        msg: 
          type: string 
    term: 
      type: object 
      required: 
        - title 
        - token 
        - doc_id 
        - line_index 
        - token_index 
      properties: 
        title: 
          description: | 
            Title of the document to which the term belongs. 
          type: string 
        token: 
          description: | 
            The term to be added to the index. 
          type: string 
        doc_id: 
          description: | 
            The unique hash for each document. 
          type: string 
        line_index: 
          description: | 
            Line index at which the term occurs in the document. 
          type: integer 
        token_index: 
          description: | 
            Position of the term in the document. 
          type: integer 
    terms: 
      type: object 
      properties: 
        code: 
          type: integer 
        data: 
          type: array 
          items: 
            $ref: '#/components/schemas/term' 
    results: 
      type: object 
      properties: 
        count: 
          type: integer 
        data: 
          type: array 
          items: 
            $ref: '#/components/schemas/result' 
    result: 
      type: object 
      properties: 
        doc_id: 
          type: string 
        score: 
          type: integer

The two API specifications describe how the two components will interact with each other and also the user. However, this is not the complete picture because even though we have shown only two API definitions, the actual implementation will have three instances of Librarian!

The user interacts with Goophr by interacting with Concierge via /api/feeder and /api/query. Concierge can further interact with the three librarian instances via /api/index and /api/query. The figure below shows what the application will look like in broad terms:

Consider when we need to build a real web application that will be used by multiple users; in this case, we'll want to have multiple instances of our services running so that they can serve all the users simultaneously. We might also have split our application into multiple APIs, and we need to have a good understanding on how to design our system to handle such distributed workload. So, in order to understand how to deal with such a system, we will work with three instances of Librarian.