openapi: 3.0.0

info:
  title: Notary Server
  description: Notary server written in Rust to provide notarization service.
  version: 0.1.0-alpha.6

tags:
  - name: General
  - name: Notarization

paths:
  /healthcheck:
    get:
      tags:
        - General
      description: Healthcheck endpoint
      parameters:
        - in: header
          name: Authorization
          description: Whitelisted API key if auth module is turned on
          schema:
            type: string
          required: false
      responses:
        "200":
          description: Ok response from server
          content:
            text/plain:
              schema:
                type: string
                example: "Ok"
        "401":
          description: API key is invalid
          content:
            text/plain:
              schema:
                type: string
                example: "Unauthorized request from prover: Invalid API key."
  /info:
    get:
      tags:
        - General
      description: General information about the notary server
      parameters:
        - in: header
          name: Authorization
          description: Whitelisted API key if auth module is turned on
          schema:
            type: string
          required: false
      responses:
        "200":
          description: Info response from server
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InfoResponse"
        "401":
          description: API key is invalid
          content:
            text/plain:
              schema:
                type: string
                example: "Unauthorized request from prover: Invalid API key."
  /session:
    post:
      tags:
        - Notarization
      description: Initialize and configure notarization for both TCP and WebSocket clients
      parameters:
        - in: header
          name: Content-Type
          description: The value must be application/json
          schema:
            type: string
            enum:
              - "application/json"
          required: true
        - in: header
          name: Authorization
          description: Whitelisted API key if auth module is turned on
          schema:
            type: string
          required: false
      requestBody:
        description: Notarization session request to server
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotarizationSessionRequest"
      responses:
        "200":
          description: Notarization session response from server
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotarizationSessionResponse"
        "400":
          description: Configuration parameters or headers provided by prover are invalid
          content:
            text/plain:
              schema:
                type: string
                example: "Invalid request from prover: Failed to deserialize the JSON body into the target type"
        "401":
          description: API key is invalid
          content:
            text/plain:
              schema:
                type: string
                example: "Unauthorized request from prover: Invalid API key."
        "500":
          description: There was some internal error when processing
          content:
            text/plain:
              schema:
                type: string
                example: "Something is wrong"
  /notarize:
    get:
      tags:
        - Notarization
      description: Start notarization for TCP client
      parameters:
        - in: header
          name: Connection
          description: The value should be 'Upgrade'
          schema:
            type: string
            enum:
              - "Upgrade"
          required: true
        - in: header
          name: Upgrade
          description: The value should be 'TCP'
          schema:
            type: string
            enum:
              - "TCP"
          required: true
        - in: query
          name: sessionId
          description: Unique ID returned from server upon calling POST /session
          schema:
            type: string
          required: true
      responses:
        "101":
          description: Switching protocol response
        "400":
          description: Headers provided by prover are invalid
          content:
            text/plain:
              schema:
                type: string
                example: "Invalid request from prover: Upgrade header is not set for client"
        "500":
          description: There was some internal error when processing
          content:
            text/plain:
              schema:
                type: string
                example: "Something is wrong"

components:
  schemas:
    NotarizationSessionRequest:
      type: object
      properties:
        clientType:
          description: Types of client that the prover is using
          type: string
          enum:
            - "Tcp"
            - "Websocket"
        maxSentData:
          description: Maximum data that can be sent by the prover in bytes
          type: integer
        maxRecvData:
          description: Maximum data that can be received by the prover in bytes
          type: integer
      required:
        - "clientType"
    NotarizationSessionResponse:
      type: object
      properties:
        sessionId:
          description: Unique ID returned from server upon calling POST /session
          type: string
      required:
        - "sessionId"
    InfoResponse:
      type: object
      properties:
        version:
          description: Current version of notary server
          type: string
        publicKey:
          description: Public key of notary server for its notarization transcript signature
          type: string
        gitCommitHash:
          description: The git commit hash of source code that this notary server is running
          type: string
        gitCommitTimestamp:
          description: The git commit timestamp of source code that this notary server is running
          type: string
      required:
        - "version"
        - "publicKey"
        - "gitCommitHash"
        - "gitCommitTimestamp"