From 93c9dda24ff475d8a7f7e57a4f78e77c32f662e8 Mon Sep 17 00:00:00 2001
From: Gesina Phillips <gesina@psc.edu>
Date: Fri, 31 Jan 2025 16:34:43 -0500
Subject: [PATCH] updated api documentation

---
 .../resources/abstract_resource.py            | 14 +++++++
 .../resources/slurm_api_resource.py           | 15 ++-----
 .../views/workspace_view.py                   |  3 +-
 user-workspaces-spec.yaml                     | 40 +++++++++++++++++++
 4 files changed, 60 insertions(+), 12 deletions(-)

diff --git a/src/user_workspaces_server/controllers/resources/abstract_resource.py b/src/user_workspaces_server/controllers/resources/abstract_resource.py
index 5507841..e312794 100644
--- a/src/user_workspaces_server/controllers/resources/abstract_resource.py
+++ b/src/user_workspaces_server/controllers/resources/abstract_resource.py
@@ -48,3 +48,17 @@ def validate_options(self, resource_options: dict) -> bool:
             logging.error(f"Validation errors: {validator.errors}")
             raise ValidationException(f"Invalid resource options found: {validator.errors}")
         return validator.is_valid
+
+    def translate_option_name(self, option: str) -> str:
+        return self.config.get("parameter_mapping", {}).get(option)
+
+    def translate_options(self, resource_options: dict) -> dict:
+        return self.translated_options(resource_options)
+
+    def translated_options(self, resource_options: dict) -> dict:
+        translated_options = {}
+        for option_name, option_value in resource_options.items():
+            if updated_option_name := self.translate_option_name(option_name):
+                translated_options[updated_option_name] = option_value
+
+        return translated_options
diff --git a/src/user_workspaces_server/controllers/resources/slurm_api_resource.py b/src/user_workspaces_server/controllers/resources/slurm_api_resource.py
index 059981a..eb04bfa 100644
--- a/src/user_workspaces_server/controllers/resources/slurm_api_resource.py
+++ b/src/user_workspaces_server/controllers/resources/slurm_api_resource.py
@@ -226,17 +226,10 @@ def get_user_token(self, external_user):
 
     def translate_options(self, resource_options):
         # Should translate the options into a format that can be used by the resource
-        updated_options = {}
-        for option_name, option_value in resource_options.items():
-            if updated_option_name := self.translate_option_name(option_name):
-                updated_options[updated_option_name] = option_value
-
+        translated_options = self.translated_options(resource_options)
         gpu_enabled = resource_options.get("gpu_enabled", False)
         if isinstance(gpu_enabled, bool) and gpu_enabled:
-            updated_options["tres_per_job"] = "gres/gpu=1"
+            translated_options["tres_per_job"] = "gres/gpu=1"
             if gpu_partition := self.config.get("gpu_partition"):
-                updated_options["partition"] = gpu_partition
-        return updated_options
-
-    def translate_option_name(self, option: str) -> str:
-        return self.config.get("parameter_mapping", {}).get(option)
+                translated_options["partition"] = gpu_partition
+        return translated_options
diff --git a/src/user_workspaces_server/views/workspace_view.py b/src/user_workspaces_server/views/workspace_view.py
index c8e3d18..16b0e28 100644
--- a/src/user_workspaces_server/views/workspace_view.py
+++ b/src/user_workspaces_server/views/workspace_view.py
@@ -263,6 +263,7 @@ def put(self, request, workspace_id, put_type=None):
 
             if not resource.validate_options(resource_options):
                 raise ParseError("Invalid resource options found.")
+            translated_options = resource.translate_options(resource_options)
 
             # TODO: Check whether user has permission for this resource (and resource storage).
 
@@ -276,7 +277,7 @@ def put(self, request, workspace_id, put_type=None):
                     "request_job_details": job_details,
                     "current_job_details": {},
                 },
-                "resource_options": resource_options,
+                "resource_options": translated_options,
                 "resource_name": type(resource).__name__,
                 "status": "pending",
                 "resource_job_id": -1,
diff --git a/user-workspaces-spec.yaml b/user-workspaces-spec.yaml
index 981db18..a8b1a46 100644
--- a/user-workspaces-spec.yaml
+++ b/user-workspaces-spec.yaml
@@ -198,6 +198,33 @@ components:
           type: string
         success:
           type: boolean
+    ParametersResponse:
+      type: object
+      properties:
+        parameters:
+          type: array
+          items:
+            type: object
+            properties:
+              display_name:
+                type: string
+              description:
+                type: string
+              variable_name:
+                type: string
+              default_value:
+                type: integer
+              validation:
+                type: object
+                properties:
+                  type:
+                    type: string
+                  min:
+                    type: integer
+                  max:
+                    type: integer
+                  required:
+                    type: boolean
 paths:
   '/workspaces/':
     get:
@@ -457,7 +484,20 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/JobTypeResponse'
+  '/parameters/':
+    get:
+      tags:
+        - Parameters
+      summary: Get the parameters that may be passed in JSON body of request.
+      responses:
+        "200":
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ParametersResponse'
 tags:
   - name: Workspaces
   - name: Jobs
   - name: JobTypes
+  - name: Parameters