From 597e9fd5d4b81e2eed737270ef3d3b70f1de1ab8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= <sybren@blender.org>
Date: Fri, 8 Jul 2022 16:10:22 +0200
Subject: [PATCH] OAPI: add operations for the First Time Wizard

Manifest task: T99437
---
 pkg/api/flamenco-openapi.yaml | 71 ++++++++++++++++++++++++++++++++++-
 1 file changed, 70 insertions(+), 1 deletion(-)

diff --git a/pkg/api/flamenco-openapi.yaml b/pkg/api/flamenco-openapi.yaml
index b0877cda..1f255820 100644
--- a/pkg/api/flamenco-openapi.yaml
+++ b/pkg/api/flamenco-openapi.yaml
@@ -41,6 +41,49 @@ paths:
             application/json:
               schema: { $ref: "#/components/schemas/ManagerConfiguration" }
 
+  /api/v3/configuration/check/shared-storage:
+    summary: Validate a path for use as shared storage.
+    post:
+      summary: Validate a path for use as shared storage.
+      operationId: checkSharedStoragePath
+      tags: [meta]
+      requestBody:
+        description: 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/PathCheckResult" }
+        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
+      in OpenAPI, but follows the `internal/manager/config` package.
+    get:
+      summary: Retrieve the configuration of Flamenco Manager.
+      operationId: getConfigurationFile
+      tags: [meta]
+      responses:
+        "200":
+          description: Normal response.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+            application/yaml:
+              schema:
+                type: string
+
   /api/v3/configuration/variables/{audience}/{platform}:
     summary: Endpoint for getting the variables from Flamenco Manager's configuration.
     get:
@@ -902,7 +945,13 @@ components:
         "shamanEnabled":
           description: Whether the Shaman file transfer API is available.
           type: boolean
-      required: [storageLocation, shamanEnabled]
+        "isFirstRun":
+          description: >
+            Whether this is considered the first time the Manager runs. This is
+            determined by a few factors, like a non-existent configuration file
+            or certain settings being empty while they shouldn't be.
+          type: boolean
+      required: [storageLocation, shamanEnabled, isFirstRun]
 
     ManagerVariables:
       description: Mapping from variable name to its properties.
@@ -928,6 +977,26 @@ components:
       type: string
       enum: [workers, users]
 
+    PathCheckInput:
+      type: object
+      properties:
+        "path": { type: string }
+      required: [path]
+
+    PathCheckResult:
+      type: object
+      properties:
+        "path":
+          description: The path that was checked.
+          type: string
+        "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, is_usable, cause]
+
     WorkerRegistration:
       type: object
       required: [secret, platform, supported_task_types, name]