server/swagger.yaml

# see also: https://github.com/hjacobs/connexion-example

swagger: '2.0'
info:
  title: BERT-viz API
  version: "0.0.1"
consumes:
  - application/json
produces:
  - application/json
basePath: /api

# ===============================================================================
## DEFINE API ##
# ===============================================================================
paths:

  /get-model-details:
    get:
      tags: [All]
      operationId: main.get_model_details
      summary: Get necessary information about the model, such as number of layers and heads
      parameters:
        - name: model
          description: Short string representing pretrained model, such as 'bert-base-uncased'
          in: query
          type: string
      responses:
        200:
          description: Returns information about the model

  /attend+meta:
    get:
      tags: [All]
      operationId: main.get_attention_and_meta
      summary: Get the attention information, BERT Embeddings, and spacy meta info for an input sentence
      parameters:
        - name: model
          description: Which pretrained transformer information is requested from
          in: query
          type: string
        - name: sentence
          description: Sentence to analyze
          in: query
          type: string
        - name: layer
          description: Layer to get attentions at
          in: query
          type: number
      responses:
        200:
          description: Returns attentions, embeddings, and metadata

  /update-mask:
    post:
      tags: [All]
      operationId: main.update_masked_attention
      summary: Get the masked attention information of tokens given indices to mask
      parameters:
        - name: payload
          description: Main contents
          in: body
          schema:
            $ref: '#/definitions/maskPayload'
      responses:
        200:
          description: Update BERT's masked behavior for passed tokens

  /k-nearest-embeddings:
    get:
      tags: [All]
      operationId: main.nearest_embedding_search
      summary: Search for the nearest embeddings to a token sent from the frontend by layer
      parameters:
        - name: model
          description: Which model to get information from
          in: query
          type: string
        - name: corpus
          description: Which corpus to search
          in: query
          type: string
        - name: embedding
          description: Query vector on which to search the dataset
          in: query
          type: array
          items:
              type: number
        - name: layer
          description: Which layer to search the nearest for
          in: query
          type: number
        - name: heads
          description: List of heads to search for
          in: query
          type: array
          items:
            type: number
        - name: k
          description: How many nearest neighbors to grab
          in: query
          type: number
      responses:
        200:
          description: Return related embeddings and associated metadata

  /k-nearest-contexts:
    get:
      tags: [All]
      operationId: main.nearest_context_search
      summary: Search for the nearest embeddings BY SELECTED HEADS to a token sent from the frontend by layer
      parameters:
        - name: model
          description: Which model to get information from
          in: query
          type: string
        - name: corpus
          description: Which corpus to search
          in: query
          type: string
        - name: context
          description: Query vector on which to search the dataset
          in: query
          type: array
          items:
              type: number
        - name: layer
          description: Which layer to search the nearest for
          in: query
          type: number
        - name: heads
          description: List of heads to search for
          in: query
          type: array
          items:
            type: number
        - name: k
          description: How many nearest neighbors to grab
          in: query
          type: number
      responses:
        200:
          description: Return related embeddings by that head and the associated metadata

definitions:
  maskPayload:
    type: object
    properties:
      model: 
        type: string
        description: Which model to get results from
      tokens:
        type: array
        items: 
          type: string
        description: Main sentence tokens to analyze
      sentence:
        type: string
        description: The original sentence the tokens came from, for extracting metadata
      mask:
        type: array
        items: 
          type: number
        description: Indices of tokens to mask
      layer:
        type: number
        description: Layer to get results for
      
    required:
      - model
      - tokens
      - sentence
      - mask
      - layer