swagger: "2.0"
info:
  description: "Cinder Scheduling Service"
  version: "1.0.0"
  title: "cinder-scheduling"
  contact:
    name: "Infra"
    email: "infrateam@zoox.com"
    url: "https://git.zooxlabs.com/zooxco/driving"

basePath: "/api/v1"

schemes:
  - "https"

paths:
  /schedule:
    post:
      summary: "Schedule a new build"
      description: ""
      operationId: "ci.cinder.scheduling_service.server.schedule"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "build"
          schema:
            $ref: "#/definitions/BuildToSchedule"
      responses:
        "200":
          description: "Successfully validated build but did not schedule it (as requested by dryRun)"
          schema:
            $ref: "#/definitions/ScheduledBuild"
        "201":
          description: "Successfully scheduled build"
          schema:
            $ref: "#/definitions/ScheduledBuild"
        "422":
          description: "Invalid parameter"
          schema:
            $ref: "#/definitions/ErrorResponse"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/ErrorResponse"
  /github-webhook:
    post:
      summary: "Incoming webhook from GitHub"
      description: ""
      operationId: "ci.cinder.scheduling_service.server.github_webhook"
      produces:
        - "application/json"
      parameters:
        - in: "body"
          name: "payload"
          schema:
            $ref: "#/definitions/GithubWebhook"
      responses:
        "201":
          description: "Successfully scheduled build"
          schema:
            $ref: "#/definitions/ScheduledBuild"
        "204":
          description: "No content"
        "422":
          description: "Invalid parameter"
          schema:
            $ref: "#/definitions/ErrorResponse"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/ErrorResponse"
  /cancel/{buildId}:
    parameters:
      - in: "path"
        name: "buildId"
        description: "buildId to cancel"
        type: "string"
        format: "uuid"
        required: true
    post:
      summary: "Cancels a build (stops the underlying job (e.g. pipedream pipeline) and marks the incomplete jobs as TERMINATED)"
      description: ""
      operationId: "ci.cinder.scheduling_service.server.cancel"
      produces:
        - "application/json"
      responses:
        "200":
          description: "Successfully cancelled the build"
          schema:
            $ref: "#/definitions/CancelBuildResult"
        "422":
          description: "Invalid parameter"
          schema:
            $ref: "#/definitions/ErrorResponse"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/ErrorResponse"
  /pipelines:
    get:
      summary: "List available pipelines"
      description: ""
      operationId: "ci.cinder.scheduling_service.server.get_pipelines"
      responses:
        "200":
          description: "Successfully retrieved pipelines"
          schema:
            $ref: "#/definitions/Pipelines"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/ErrorResponse"
  /schedules:
    get:
      summary: "List job schedules"
      description: ""
      operationId: "ci.cinder.scheduling_service.server.get_schedules"
      responses:
        "200":
          description: "Successfully retrieved schedules"
          schema:
            $ref: "#/definitions/Schedules"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/ErrorResponse"
  /config:
    get:
      summary: "Returns the static config from the server"
      description: ""
      operationId: "ci.cinder.scheduling_service.server.get_config"
      responses:
        "200":
          description: "Successfully retrieved config"
          schema:
            $ref: "#/definitions/Config"
        "500":
          description: "Internal server error"
          schema:
            $ref: "#/definitions/ErrorResponse"
  /health/status:
    get:
      summary: "Health check"
      description: ""
      operationId: "ci.cinder.scheduling_service.server.health"
      responses:
        "200":
          description: "Healthy"
          schema:
            $ref: "#/definitions/HealthResponse"
        "500":
          description: "Unhealthy"
          schema:
            $ref: "#/definitions/HealthResponse"

definitions:
  BuildToSchedule:
    type: "object"
    properties:
      pipeline:
        description: "Pipeline to schedule."
        type: "string"
      trigger:
        description: "Name of trigger e.g. Jane Doe, Webhook"
        type: "string"
      githubOwner:
        description: "GitHub owner hosting the code to test"
        type: "string"
      githubRepo:
        description: "GitHub repo hosting the code to test"
        type: "string"
      gitSha:
        description: "Git sha to test. If not set, will use the HEAD of the provided branch."
        type: "string"
      gitBranch:
        description: "Git branch to test."
        type: "string"
      suffix:
        description: "Suffix to add to the pipeline name to create the build name. Defaults to the git branch if unset."
        type: "string"
      variables:
        description: "Variables to set for all plans unless they are specified on a specific pipeline plan."
        $ref: "#/definitions/Variables"
      pipelinePlanVariables:
        description: "Variables to set for specific pipeline plans."
        type: "object"
        additionalProperties:
          $ref: "#/definitions/Variables"
      pipelinePlanWhitelist:
        description: "List of pipeline plans to run. If not empty, filters out plans not listed here."
        type: "array"
        items:
          type: "string"
      priority:
        description: "Priority to set for the scheduled pipeline."
        type: "string"
        enum:
          - "HIGHEST"
          - "HIGH"
          - "MEDIUM"
          - "LOW"
          - "LOWEST"
      dryRun:
        description: "Don't schedule the build but merely validate arguments."
        type: "boolean"
      allowReservedVariables:
        description: "Allow reserved variables to be set and ignored when scheduling. If false, validation will fail if reserved variables are provided."
        type: "boolean"
    required:
      - "pipeline"
      - "trigger"

  Variables:
    type: "object"
    additionalProperties:
      type: "string"

  ScheduledBuild:
    type: "object"
    properties:
      buildId:
        description: "Build id for the created build (references the build service)"
        type: "string"
      message:
        description: "Message from scheduling library"
        type: "string"

  # This takes many different forms and varies greatly based on the type of
  # event.
  GithubWebhook:
    type: "object"
    additionalProperties: true

  CancelBuildResult:
    type: "object"
    properties:
      success:
        description: "True iff successfully cancelled the build"
        type: "boolean"
      message:
        description: "Message from scheduling library"
        type: "string"

  Pipelines:
    type: "object"
    properties:
      pipelines:
        description: "List of pipelines"
        type: "array"
        items:
          $ref: "#/definitions/Pipeline"

  Pipeline:
    type: "object"
    properties:
      name:
        description: "The name of the pipeline"
        type: "string"
      variables:
        description: "List of merged variables for all pipeline plans"
        type: "array"
        items:
          $ref: "#/definitions/Variable"
      pipelinePlans:
        description: "PipelinePlans in this Pipeline"
        type: "array"
        items:
          $ref: "#/definitions/PipelinePlan"

  PipelinePlan:
    type: "object"
    properties:
      name:
        description: "The name of the pipeline plan"
        type: "string"
      planName:
        description: "The name of the plan"
        type: "string"
      deps:
        description: "Names of other pipeline plans that this pipeline plan depends on"
        type: "array"
        items:
          type: "string"
      variables:
        description: "List of variables to configure this pipeline plan"
        type: "array"
        items:
          $ref: "#/definitions/Variable"

  Variable:
    type: "object"
    properties:
      name:
        description: "Variable name"
        type: "string"
      required:
        description: "True iff the variable must be set to schedule the job"
        type: "boolean"
      hidden:
        description: "True iff the variable shouldn't be displayed prominently to the user"
        type: "boolean"
      reserved:
        description: "True iff the variable must not be set when scheduling jobs"
        type: "boolean"
      doc:
        description: "Documentation (if any) for the variable"
        type: "string"

  Schedules:
    type: "object"
    properties:
      schedules:
        description: "List of schedules"
        type: "array"
        items:
          $ref: "#/definitions/Schedule"

  Schedule:
    type: "object"
    properties:
      name:
        description: "Name of the schedule"
        type: "string"
      pipeline:
        description: "Name of the pipeline it will schedule"
        type: "string"
      scheduleUtc:
        description: "Cron schedule in UTC"
        type: "string"
      gitBranch:
        description: "Git repository branch name"
        type: "string"
      githubOwner:
        description: "GitHub owner"
        type: "string"
      githubRepo:
        description: "GitHub repo"
        type: "string"
      variables:
        description: "Variables set for all pipeline plans"
        $ref: "#/definitions/Variables"

  Config:
    type: "object"
    properties:
      config:
        description: "Config values"
        type: "object"
        additionalProperties:
          type: "string"

  HealthResponse:
    type: "object"
    properties:
      message:
        description: "A message describing the health"
        type: "string"

  ErrorResponse:
    type: "object"
    properties:
      message:
        description: "A message describing the error"
        type: "string"
