swagger: "2.0"
info:
  description: "Tells Robot which endpoint to use for services."
  version: "1.0.0"
  title: "RALph"
  contact:
    name: "Infra"
    email: "infrateam@zoox.com"
    url: "https://git.zooxlabs.com/zooxco/driving"
basePath: /v1
paths:
  /robots/{robot_id}/services/:
    parameters:
      - $ref: "#/parameters/RobotId"
    get:
      summary: "Find services for a robot. These will take into defaults and overrides."
      operationId: "findServices"
      produces:
        - application/json
      responses:
        "200":
          description: "Successfully retrieved robot's services."
          schema:
            $ref: "#/definitions/ServiceList"
        "500":
          description: "Internal server error."
          schema:
            $ref: "#/definitions/ErrorInfo"
  /robots/{robot_id}/services/{service_id}:
    parameters:
      - $ref: "#/parameters/RobotId"
      - $ref: "#/parameters/ServiceId"
    get:
      summary: "Get a service for a robot. This will take into defaults and overrides."
      operationId: "getService"
      produces:
        - application/json
      responses:
        "200":
          description: "Successfully retrieved robot's service."
          schema:
            $ref: "#/definitions/Service"
        "404":
          description: "Robot or service not found."
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Internal server error."
          schema:
            $ref: "#/definitions/ErrorInfo"
  /robots/{robot_id}/services/{service_id}/override:
    parameters:
      - $ref: "#/parameters/RobotId"
      - $ref: "#/parameters/ServiceId"
    get:
      summary: "Get the robot's override for this service."
      operationId: "getOverride"
      produces:
        - "application/json"
      responses:
        "200":
          description: "The override."
          schema:
            $ref: "#/definitions/ServiceOverride"
        "404":
          description: "Robot or service not found."
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Internal server error."
          schema:
            $ref: "#/definitions/ErrorInfo"
    put:
      summary: "Set/update the robot's override."
      operationId: "updateOverride"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "serviceOverride"
          description: "A service for a specific robot."
          required: true
          schema:
            $ref: "#/definitions/ServiceOverride"
      responses:
        "200":
          description: "Override set."
          schema:
            $ref: "#/definitions/ServiceOverride"
        "404":
          description: "Robot or service not found."
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Internal server error."
          schema:
            $ref: "#/definitions/ErrorInfo"
    delete:
      summary: "Unset the robot's override."
      operationId: "deleteOverride"
      produces:
        - application/json
      responses:
        "204":
          description: "Override deleted."
        "404":
          description: "Robot or service not found."
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Internal server error."
          schema:
            $ref: "#/definitions/ErrorInfo"
  /service-overrides/:
    get:
      parameters:
        - $ref: "#/parameters/RobotIdQuery"
        - $ref: "#/parameters/ServiceIdQuery"
      summary: "Find service overrides."
      operationId: "findOverrides"
      produces:
        - application/json
      responses:
        "200":
          description: "Matching overrides."
          schema:
            $ref: "#/definitions/ServiceList"
        "500":
          description: "Internal server error."
          schema:
            $ref: "#/definitions/ErrorInfo"
  /service-defaults/:
    get:
      summary: "Find default services."
      operationId: "findDefaults"
      produces:
        - application/json
      responses:
        "200":
          description: "Default services."
          schema:
            $ref: "#/definitions/ServiceList"
        "500":
          description: "Internal server error."
          schema:
            $ref: "#/definitions/ErrorInfo"
  /service-defaults/{service_id}:
    parameters:
      - $ref: "#/parameters/ServiceId"
    get:
      summary: "Get default services."
      operationId: "getDefault"
      produces:
        - application/json
      responses:
        "200":
          description: "Got the default."
          schema:
            $ref: "#/definitions/ServiceDefault"
        "404":
          description: "Default not found."
          schema:
            $ref: "#/definitions/ErrorInfo"
        "500":
          description: "Internal server error."
          schema:
            $ref: "#/definitions/ErrorInfo"
    put:
      summary: "Set/update default service."
      operationId: "updateDefault"
      consumes:
        - "application/json"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "serviceDefault"
          description: "A default service to use when a robot doesn't have an override."
          required: true
          schema:
            $ref: "#/definitions/ServiceDefault"
      responses:
        "200":
          description: "Default service set."
          schema:
            $ref: "#/definitions/Service"
        "500":
          description: "Internal server error."
          schema:
            $ref: "#/definitions/ErrorInfo"
    delete:
      summary: "Delete service. Will also delete any overrides."
      operationId: "deleteDefault"
      produces:
        - application/json
      responses:
        "204":
          description: "Service deleted."
        "500":
          description: "Internal server error."
          schema:
            $ref: "#/definitions/ErrorInfo"
definitions:
  Service:
    type: object
    discriminator: "serviceType"
    properties:
      id:
        type: "string"
        description: "Service id/name."
        readOnly: true
      url:
        type: "string"
        description: "URL to be used for this service."
      serviceType:
        type: "string"
    required:
      - url
      - serviceType
  ServiceDefault:
    allOf:
      - $ref: "#/definitions/Service"
  ServiceOverride:
    allOf:
      - $ref: "#/definitions/Service"
      - type: "object"
        properties:
          robotId:
            type: "string"
            format: "uuid"
            description: "robot id/name."
            readOnly: true
          ttlSeconds:
            type: "number"
            description: "How long this override will last before reverting back to the default."
  ServiceList:
    type: object
    properties:
      items:
        type: array
        items:
          $ref: "#/definitions/Service"
    required:
      - items
  ErrorInfo:
    type: "object"
    description: "Resource representing the error information"
    properties:
      statusCode:
        type: "integer"
        description: "Error code."
      message:
        type: "string"
        description: "Message describing the error."
    required:
      - statusCode
      - message
parameters:
  RobotId:
    name: "robot_id"
    in: "path"
    type: "string"
    format: "uuid"
    description: "Id of the robot."
    required: true
  ServiceId:
    name: "service_id"
    in: "path"
    type: "string"
    pattern: "^[a-z0-9-]+$"
    description: "Service id/name."
    required: true
  ServiceIdQuery:
    name: "service_id"
    in: "query"
    type: "string"
    pattern: "^[a-z0-9-]+$"
    description: "Service id/name."
  RobotIdQuery:
    name: "robot_id"
    in: "query"
    type: "string"
    format: "uuid"
    description: "Robot id."
