From 186dd064014df0ea2f874c8b34efec5d6edc77c4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= <sybren@blender.org>
Date: Tue, 12 Jul 2022 16:43:11 +0200
Subject: [PATCH] OAPI: endpoints for finding & checking Blender executables

These will be used in the first-time wizard.
---
 pkg/api/flamenco-openapi.yaml | 75 ++++++++++++++++++++++++++++++++++-
 1 file changed, 74 insertions(+), 1 deletion(-)

diff --git a/pkg/api/flamenco-openapi.yaml b/pkg/api/flamenco-openapi.yaml
index 1f255820..77ed7ad6 100644
--- a/pkg/api/flamenco-openapi.yaml
+++ b/pkg/api/flamenco-openapi.yaml
@@ -64,6 +64,44 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/Error" }
 
+  /api/v3/configuration/check/blender:
+    summary: Find & validate a Blender executable.
+    get:
+      summary: Find one or more CLI commands for use as way to start Blender
+      operationId: findBlenderExePath
+      tags: [meta]
+      responses:
+        "200":
+          description: Found locations of Blender.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/BlenderPathFindResult" }
+        default:
+          description: Something went wrong.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Error" }
+    post:
+      summary: Validate a CLI command for use as way to start Blender
+      operationId: checkBlenderExePath
+      tags: [meta]
+      requestBody:
+        description: Command or executable path to check
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/PathCheckInput" }
+      responses:
+        "200":
+          description: Normal response, path check went fine.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/BlenderPathCheckResult" }
+        default:
+          description: Something went wrong.
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Error" }
+
   /api/v3/configuration/file:
     summary: >
       Access to the configuration file of Flamenco Manager. This is not schema'd
@@ -993,10 +1031,45 @@ components:
           description: Whether the path is usable or not.
           type: boolean
         "cause":
-          description: Description of why this path is not usable.
+          description: Description of why this path is (not) usable.
           type: string
       required: [path, is_usable, cause]
 
+    BlenderPathFindResult:
+      type: array
+      items:
+        $ref: "#/components/schemas/BlenderPathCheckResult"
+
+    BlenderPathCheckResult:
+      type: object
+      properties:
+        "input":
+          description: The input that was given to find this Blender.
+          type: string
+        "path":
+          description: The path that was found.
+          type: string
+        "source":
+          $ref: "#/components/schemas/BlenderPathSource"
+        "is_usable":
+          description: Whether the path is usable or not.
+          type: boolean
+        "cause":
+          description: Description of why this path is (not) usable.
+          type: string
+      required: [path, source, is_usable, cause]
+
+    BlenderPathSource:
+      type: string
+      enum:
+        # The reported path is the result of inspecting the association with .blend files.
+        # This is only checked when the input path is empty.
+        - file_association
+        # The input path was interpreted as simple command, and found on $PATH.
+        - path_envvar
+        # The input path was used as-is, as it points to an existing binary.
+        - input_path
+
     WorkerRegistration:
       type: object
       required: [secret, platform, supported_task_types, name]