openapi: 3.0.0
info:
  version: 1.0.0
  title: Flamenco manager
  description: Render Farm manager API
  contact:
    name: Flamenco Team
    url: https://flamenco.io/
  license:
    name: GPLv3
    url: https://www.gnu.org/licenses/gpl-3.0.en.html
servers:
  - url: /
paths:
  /api/worker/register-worker:
    summary: Registration of new workers
    post:
      summary: Register a new worker
      operationId: registerWorker
      tags: [worker]
      requestBody:
        description: Worker to register
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WorkerRegistration"
      responses:
        "200":
          description: normal response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RegisteredWorker"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/worker/task:
    summary: Task scheduler endpoint.
    post:
      operationId: scheduleTask
      summary: Obtain a new task to execute
      security: [{worker_auth: []}]
      tags: [worker]
      responses:
        "204":
          description: No tasks available for this Worker.
        "200":
          description: Task to execute.
          content:
            application/json:
              schema: {$ref: "#/components/schemas/AssignedTask"}
        "403":
          description: Permission Denied
          content:
            application/json:
              schema: {$ref: "#/components/schemas/SecurityError"}

  /api/jobs/types:
    summary: Available Flamenco job types.
    get:
      operationId: getJobTypes
      summary: Get list of job types and their parameters.
      tags: [jobs]
      responses:
        "200":
          description: Available job types
          content:
            application/json:
              schema: {$ref: "#/components/schemas/AvailableJobTypes"}

  /api/jobs:
    summary: Job submission endpoint.
    post:
      operationId: submitJob
      summary: Submit a new job for Flamenco Manager to execute.
      tags: [jobs]
      # TODO: Security!
      requestBody:
        description: Job to submit
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubmittedJob"
      responses:
        "200":
          description: Job was succesfully compiled into individual tasks.
          content:
            application/json:
              schema: {$ref: "#/components/schemas/SubmittedJob"}
        default:
          description: Error message
          content:
            application/json:
              schema: {$ref: "#/components/schemas/Error"}

tags:
  - name: jobs
    description: Blablabla for users to get job metadata balbla
  - name: worker
    description: API for Flamenco Workers to communicate with Flamenco Manager.

components:
  schemas:
    WorkerRegistration:
      type: object
      required: [secret, platform, supported_task_types, nickname]
      properties:
        secret: {type: string}
        platform: {type: string}
        supported_task_types:
          type: array
          items: {type: string}
        nickname: {type: string}

    RegisteredWorker:
      type: object
      properties:
        id: {type: string}
        nickname: {type: string}
        address: {type: string}
        status: {type: string}
        platform: {type: string}
        last_activity: {type: string}
        software: {type: string}
        supported_task_types:
          type: array
          items: {type: string}
      required: [id, nickname, address, status, platform, current_task, last_activity, software, supported_task_types]

    AssignedTask:
      type: object
      description: AssignedTask is a task as it is received by the Worker.
      properties:
        id: {type: string}
        job: {type: string}
        user: {type: string}
        name: {type: string}
        status: {$ref: "#/components/schemas/TaskStatus"}
        priority: {type: integer}
        job_priority: {type: integer}
        job_type: {type: string}
        task_type: {type: string}
        commands:
          type: array
          items: {$ref: "#/components/schemas/Command"}
      required: [id, job, user, name, status, priority, job_priority, job_type, task_type, commands]

    JobStatus:
      type: string
      enum: [active, canceled, completed, construction-failed, failed, paused, queued, archived, archiving, cancel-requested, fail-requested, requeued, under-construction, waiting-for-files]

    TaskStatus:
      type: string
      enum: [active, canceled, completed, failed, queued, soft-failed, cancel-requested, fail-requested, paused, processing]

    Command:
      type: object
      description: Command represents a single command to execute by the Worker.
      properties:
        name: {type: string}
        settings: {type: object}
      required: [name, settings]

    AvailableJobTypes:
      type: object
      description: List of job types supported by this Manager.
      properties:
        "job_types":
          type: array
          items: {$ref: "#/components/schemas/AvailableJobType"}
      required: [job_types]

    AvailableJobType:
      type: object
      description: Job type supported by this Manager, and its parameters.
      properties:
        "name": {type: string}
        "label": {type: string}
        "settings":
          type: array
          items: {$ref: "#/components/schemas/AvailableJobSetting"}
      required: [name, label, settings]

    AvailableJobSetting:
      type: object
      description: Single setting of a Job types.
      properties:
        "key":
          type: string
          description: Identifier for the setting, must be unique within the job type.
        "type": {$ref: "#/components/schemas/AvailableJobSettingType"}
        "subtype": {$ref: "#/components/schemas/AvailableJobSettingSubtype"}
        "choices":
          description: When given, limit the valid values to these choices. Only usable with string type.
          type: array
          items: {type: string}
        "default":
          description: The default value shown to the user when determining this setting.
        "visible":
          type: boolean
          description: >
            Whether to show this setting in the UI of a job submitter (like a
            Blender add-on). Set to `false` when it is an internal setting that
            shouldn't be shown to end users.
          default: true
        "required":
          type: boolean
          description: >
            Whether to immediately reject a job definition, of this type,
            without this particular setting.
          default: false
        "editable":
          type: boolean
          description: >
            Whether to allow editing this setting after the job has been
            submitted. Would imply deleting all existing tasks for this job, and
            recompiling it.
          default: false
      required: [key, type]

    AvailableJobSettingType:
      type: string
      description: >
        Type of job setting, must be usable as IDProperty type in Blender. No
        nested structures (arrays, dictionaries) are supported.
      enum: [string, int32, float, bool]

    AvailableJobSettingSubtype:
      type: string
      description: >
        Sub-type of the job setting. Currently only available for string types.
        `HASHED_FILE_PATH` is a directory path + `"/######"` appended.
      enum: ["file_path", "dir_path", "file_name", "hashed_file_path"]

    SubmittedJob:
      type: object
      description: Job definition submitted to Flamenco.
      properties:
        "id": {type: string}
        "name": {type: string}
        "type": {type: string}
        "status": {$ref: "#/components/schemas/JobStatus"}
        "priority": {type: integer, default: 50}
        "settings":
          type: object
        "metadata":
          type: object
      required: [name, type, priority]
      example:
        type: "simple-blender-render"
        name: 3Д рендеринг
        priority: 50
        settings:
          blender_cmd: "{blender}"
          filepath: "/render/sf/jobs/scene123.blend"
          render_output: "/render/sf/frames/scene123"
          frames: "1-10"
          chunk_size: 3
          fps: 24
          extract_audio: true
          images_or_video: "images"
          format: "PNG"
          output_file_extension: ".png"
        metadata:
          "user.name": "Sybren Stüvel"
          "user.email": "sybren@blender.org"
          project: "Sprite Fright"


    Error:
      type: object
      required: [code, message]
      properties:
        code: {type: integer, format: int32}
        message: {type: string}

    SecurityError:
      type: object
      required: [message]
      properties:
        message: {type: string}

    Configuration:
      type: object
      description: Flamenco Manager configuration
      properties:
        "_meta":
          type: object
          properties:
            "schema_version": {type: integer}
          required: [schema_version]
        "settings":
          description: Key-value pairs for settings.
          type: object
          additionalProperties: true
      required: [_meta, settings]

  securitySchemes:
    worker_auth:
      description: Username is the worker ID, password is the secret given at worker registration.
      type: http
      scheme: basic