# NOTE: Do not upgrade past Swagger 2. zclient does not support OpenAPI 3 unless
# https://github.com/Yelp/bravado/issues/306 is resolved.
swagger: "2.0"
info:
  description: "An open API spec project for capturing robot's information such as machine name, macaddress etc"
  version: "1.0.0"
  title: "ki_robot_info_api"
  contact:
    name: "Infra"
    email: "infrateam@zoox.com"
    url: "https://git.zooxlabs.com/zooxco/driving/knight_industries/ki_robot_info_api"
schemes:
- "http"
- "https"
basePath: "/v1/"
paths:
  /robot/:
    post:
      summary: "Adds the robot's information"
      operationId: "addRobotInfo"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "body"
        name: "robotInfo"
        description: "Robot information to be added"
        required: true
        schema:
          $ref: "#/definitions/RobotInfo"
      responses:
        "201":
          description: "Robot information was successfully added to the system"
          schema:
            $ref: "#/definitions/RobotInfo"
        "400":
          description: "Invalid input is provided check parameters"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "409":
          description: "Robot with same name already exists in the system"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Some internal server error has occurred so retry it again"
          schema:
            $ref: "#/definitions/ErrorInfo"
    get:
      summary: "Gets the list of robots information in batches ordered by the specified field"
      operationId: "getRobotInfos"
      produces:
      - "application/json"
      parameters:
      - in: "query"
        name: "sort"
        type: "string"
        description: "Name of the property (see RobotInfo) to sort up on. Defaults to name"
        default: "name"
        required: false
      - in: "query"
        name: "direction"
        type: "string"
        description: "Direction of the sorting. Can be of on asc for ascending order or desc for descending order"
        enum:
        - "ASCENDING"
        - "DESCENDING"
        default: "ASCENDING"
        required: false
      - in: "query"
        name: "limit"
        type: integer
        description: "Number of records per query"
        default: 1000
        minimum: 1
        maximum: 10000
        required: false
      - in: "query"
        name: "offset"
        type: integer
        description: "Offset for fetching records in batches. Only returns records higher than offset. Default 0 (all)."
        default: 0
        required: false
      - in: "query"
        name: "name"
        type: string
        description: "Name of the robot to search for"
        required: false
      - in: "query"
        name: "compute_major_version"
        type: string
        description: "Compute major version to search for"
        required: false
      - in: "query"
        name: "compute_minor_version"
        type: string
        description: "Compute minor version to search for"
        required: false
      responses:
        "200":
          description: "Operation was successful and robot infos are returned"
          schema:
            $ref: "#/definitions/RobotInfoList"
        "400":
          description: "Invalid input was provided, check parameters"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Some internal server error has occurred so retry it again"
          schema:
            $ref: "#/definitions/ErrorInfo"
  /robot/{robotId}:
    get:
      summary: "Provides the robot information by its id"
      operationId: "getRobotInfo"
      produces:
      - "application/json"
      parameters:
      - in: "path"
        name: "robotId"
        type: "string"
        description: "Id of the robot whose info needs to be retrieved"
        required: true
      responses:
        "200":
          description: "Operation was successful and robot info with the ID is returned"
          schema:
            $ref: "#/definitions/RobotInfo"
        "400":
          description: "Invalid input was provided, check parameters section for more details"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "404":
          description: "Robot Info with the ID was not found"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Some internal server error has occurred so retry it again"
          schema:
            $ref: "#/definitions/ErrorInfo"
    put:
      summary: "Updates the robot information"
      operationId: "updateRobotInfo"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "path"
        name: "robotId"
        type: "string"
        description: "Id of the robot whose info needs to be updated"
        required: true
      - in: "body"
        name: "robotInfo"
        description: "Robot information to be updated"
        required: true
        schema:
          $ref: "#/definitions/RobotInfo"
      responses:
        "200":
          description: "Operation was successful and robot info was successfully updated and returned"
          schema:
            $ref: "#/definitions/RobotInfo"
        "400":
          description: "Invalid input was provided, check parameters section for more details"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "404":
          description: "Robot Info with the ID was not found"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "409":
          description: "Robot with same name already exists in the system"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Some internal server error has occurred so retry it again"
          schema:
            $ref: "#/definitions/ErrorInfo"
    delete:
      summary: "Deletes the robot information when there are no machines tied to this robot"
      operationId: "deleteRobotInfo"
      parameters:
      - in: "path"
        name: "robotId"
        type: "string"
        description: "Id of the robot whose info needs to be deleted"
        required: true
      responses:
        "204":
          description: "Operation was successful and robot info was deleted successfully"
        "400":
          description: "Unable to delete robot info as it still has machines assigned. Please remove all machines of robot before removing the robot"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "404":
          description: "Robot Info with the ID was not found"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Some internal server error has occurred so retry it again"
          schema:
            $ref: "#/definitions/ErrorInfo"
  /robot/{robotId}/machine/:
    post:
      summary: "Adds a machine to a robot"
      operationId: "addMachineInfo"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "path"
        name: "robotId"
        type: "string"
        description: "Id of the robot to whom the machine info is being added"
        required: true
      - in: "body"
        name: "machineInfo"
        description: "Machine's information to be added to robot"
        required: true
        schema:
          $ref: "#/definitions/MachineInfo"
      responses:
        "201":
          description: "Machine information was successfully added to the system"
          schema:
            $ref: "#/definitions/MachineInfo"
        "400":
          description: "Invalid input was provided check parameters"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "409":
          description: "Machine with same name for the same robot already exists in the system or there is a machine with same mac address"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Some internal server error has occurred so retry it again"
          schema:
            $ref: "#/definitions/ErrorInfo"
  /machine/{machineId}:
    get:
      summary: "Provides the machine's information by its id"
      operationId: "getMachineInfo"
      produces:
      - "application/json"
      parameters:
      - in: "path"
        name: "machineId"
        type: "string"
        description: "Id of the machine info that needs to be retrieved"
        required: true
      responses:
        "200":
          description: "Operation was successful and robot info is returned"
          schema:
            $ref: "#/definitions/MachineInfo"
        "400":
          description: "Invalid input was provided check parameters"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "404":
          description: "Machine Info with ID was not found"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Some internal server error has occurred so retry it again"
          schema:
            $ref: "#/definitions/ErrorInfo"
    put:
      summary: "Updates the machine information. Please note that this Operation does not update robot Id, id or name and will ignore the change if attempted"
      operationId: "updateMachineInfo"
      consumes:
      - "application/json"
      produces:
      - "application/json"
      parameters:
      - in: "path"
        name: "machineId"
        type: "string"
        description: "Id of the machine whose info needs to be updated"
        required: true
      - in: "body"
        name: "machineInfo"
        description: "Machine's information to be updated"
        required: true
        schema:
          $ref: "#/definitions/MachineInfo"
      responses:
        "200":
          description: "Operation was successful and machine info was successfully updated and returned"
          schema:
            $ref: "#/definitions/MachineInfo"
        "400":
          description: "Invalid input was provided check parameters"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "404":
          description: "Machine Info with ID was not found"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "409":
          description: "Machine with same name for the same robot already exists in the system or there is a machine with same mac address"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Some internal server error has occurred so retry it again"
          schema:
            $ref: "#/definitions/ErrorInfo"
    delete:
      summary: "Deletes the machine information"
      operationId: "deleteMachineInfo"
      parameters:
      - in: "path"
        name: "machineId"
        type: "string"
        description: "Id of the machine whose info needs to be deleted"
        required: true
      responses:
        "204":
          description: "Operation was successful and machine info was deleted successfully"
        "404":
          description: "Machine Info with ID was not found"
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Some internal server error has occurred so retry it again"
          schema:
            $ref: "#/definitions/ErrorInfo"
definitions:
  IPMIInfo:
    description: "Resource representing IPMI information of a machine"
    type: "object"
    properties:
      MACAddress:
        type: "string"
        description: "IPMI's ethenet hardware address"
        pattern: ([0-9a-f]{2}[:]){5}([0-9a-f]{2})
      IPAddress:
        type: "string"
        pattern: "([0-9]{1,3}.){3}[0-9]{1,3}"
        description: "IP v4 address allocated for the IPMI machine"
      userName:
        type: "string"
        description: "Name of the IPMI user to be used for issuing IPMI commands"
        default: "ADMIN"
      vaultKey:
        type: "string"
        description: "Field in the vault namespace to be used to fetch password"
    required:
    - MACAddress
    - userName
  HostInfo:
    description: "Resource representing host related information of a machine"
    type: "object"
    properties:
      MACAddress:
        type: "string"
        pattern: ([0-9a-f]{2}[:]){5}([0-9a-f]{2})
        description: "Hosts 10g ethernet hadware address"
      IPAddress:
        type: "string"
        pattern: "([0-9]{1,3}.){3}[0-9]{1,3}"
        description: "IP v4 address allocated for the host machine .3 network"
      interface:
        type: "string"
        description: "The ethernet interface used on the machine."
    required:
    - MACAddress
  MachineInfo:
    description: "Resource representing each machine's information provided by the client"
    type: "object"
    properties:
      id:
        type: "string"
        description: "Unique Identifier for the resource"
        readOnly: true
      name:
        type: "string"
        description: "Name of the machine. Can be one of the pattern drc-kitt*, kittsim*, vision{1..8}, Operator, drc-vh4*, drc-vh5*, drc-pri*, drc-vh6a*, drc-vh6b*, drc-vh6c*, drc-vh6[0-9]*"
      robotId:
        type: "string"
        description: "Id of the robot to which this machine needs to added to"
      distro:
        type: "string"
        description: "Name of the cobbler distro used for imaging"
      kickstartTemplate:
        type: "string"
        description: "Name of the kickstart template used for imaging"
      ipmi:
        $ref: "#/definitions/IPMIInfo"
      host:
        $ref: "#/definitions/HostInfo"
      created:
        type: "integer"
        format: "int64"
        description: "Time in epoch seconds at which the resource has been created"
        readOnly: true
      updated:
        type: "integer"
        format: "int64"
        description: "Time in epoch seconds at which the resource has been last updated"
        readOnly: true
    required:
    - name
    - robotId
    - ipmi
    - host
  MachineInfoList:
    type: "object"
    description: "Resource representing list of MachineInfos"
    properties:
      items:
        type: "array"
        description: "Provides a list of MachineInfos"
        items:
          $ref: "#/definitions/MachineInfo"
    required:
    - items
  RobotInfo:
    description: "Resource representing robot's information provided by a client"
    type: "object"
    properties:
      id:
        type: "string"
        description: "Unique Id for the resource"
        readOnly: true
      name:
        type: "string"
        description: "Name of the robot. Should be of pattern kitt_*, zimbeast_*, vh4_*, vh5_*, pri_*"
      computeMajorVersion:
        type: "string"
        description: "Major version of the compute installed on the robot.  Currently supported '2' or '3'"
      computeMinorVersion:
        type: "string"
        description: "Minor version of the compute installed on the robot.  Currently supported '5' when major is '2' and ['2', '5'] when major version is '3'"
      operatorVersion:
        type: "string"
        description: "Version of the operator used for the robot"
        enum:
        - "LAPTOP"
        - "VULCAN"
      vaultIPMIPath:
        type: "string"
        description: "Vault path for the robot containing the IPMI account passwords. Defaults to secret/robot/ipmi/{robot_name}"
      robotNetworkType:
        type: "string"
        description: "Describes the robot network configuration.  Defaults to PEP_WAVE"
        enum:
        - "PEP_WAVE"
        - "PEP_WAVE_TUX"
        - "TCC_TUX"
        default: "PEP_WAVE"
      created:
        type: "integer"
        format: "int64"
        description: "Time in epoch seconds at which the resource has been created"
        readOnly: true
      updated:
        type: "integer"
        format: "int64"
        description: "Time in epoch seconds at which the resource has been last updated"
        readOnly: true
      visionCount:
        type: "integer"
        description: "Represents the count of vision machines in the robot"
        readOnly: true
      operatorCount:
        type: "integer"
        description: "Represents the count of operator machines (should be either 0 or 1) in the robot, 1 when OperationVersion is VULCAN otherwise 0"
        readOnly: true
      machines:
        type: "array"
        description: "Represents the list of machines that are part of this robot"
        items:
          $ref: "#/definitions/MachineInfo"
        readOnly: true
    required:
      - name
      - computeMajorVersion
      - computeMinorVersion
      - operatorVersion
  RobotInfoList:
    type: "object"
    description: "Resource representing list of RobotInfos"
    properties:
      items:
        type: "array"
        description: "Provides a list of RobotInfos"
        items:
          $ref: "#/definitions/RobotInfo"
      metaData:
        $ref: "#/definitions/ListMetaData"
    required:
    - items
    - metaData
  ErrorInfo:
    type: "object"
    description: "Resource representing the error information"
    properties:
      statusCode:
        type: "integer"
        description: "Error code"
        readOnly: true
      message:
        type: "string"
        description: "Detail info representing the error"
        readOnly: true
  ListMetaData:
    type: "object"
    description: "Provides the meta data for various list resources"
    properties:
      limit:
        type: "integer"
        description: "Max number of resources provided in the list"
      offset:
        type: "integer"
        description: "Offset from which the resources are fetched"
      orderBy:
        type: "string"
        description: "Resource's property on which resources are sorted"
      direction:
        type: "string"
        description: "Direction of the sorting order"
        enum:
        - "ASCENDING"
        - "DESCENDING"
      totalCount:
        type: "integer"
        description: "Total number of resources available"
    required:
    - limit
    - offset
    - orderBy
    - direction
    - totalCount
