apply pr reviews

Author: Leopold-Cramer

dataset/src/main/openapi/dataset.yaml

@@ -24,7 +24,9 @@ paths:
       operationId: createDataset
       tags:
         - dataset
-      description: "Create a new dataset in the workspace. Required fields: name. The dataset is initialized with empty data and can be populated through dataset parts. Creator becomes admin."
+      description: Create a new dataset in the workspace.
+          The dataset is initialized with specified parts (can be empty).
+          The dataset can also be populated through dataset parts.
       summary: Create a Dataset
       requestBody:
         content:
@@ -166,7 +168,7 @@ paths:
       operationId: getDataset
       tags:
         - dataset
-      description: "Retrieve complete information about a specific dataset including metadata, source configuration, security settings, and associated dataset parts summary."
+      description: Retrieve complete information about a specific dataset including dataset parts.
       summary: Retrieve a Dataset
       responses:
         "200":
@@ -192,7 +194,7 @@ paths:
       operationId: updateDataset
       tags:
         - dataset
-      description: "Update dataset metadata (name, description, tags). Note: Some fields cannot be modified after creation. Returns the updated dataset."
+      description: Update dataset information and return the updated dataset.
       summary: Update a Dataset
       requestBody:
         content:
@@ -235,7 +237,7 @@ paths:
       operationId: deleteDataset
       tags:
         - dataset
-      description: "Permanently delete a dataset and all its data parts. This operation cannot be undone. Returns 204 on success, 404 if not found, 409 if dataset is in use by runners."
+      description: "Permanently delete a dataset and all its data parts. This operation cannot be undone."
       summary: Delete a Dataset
       responses:
         "204":
@@ -461,7 +463,7 @@ paths:
       operationId: createDatasetPart
       tags:
         - dataset
-      description: "Create a new data part within a dataset. Specify type as 'FILE' for file uploads or 'DB' for database queries. Returns the created part with generated ID."
+      description: "Create a new data part within a dataset. Specify type as 'File' for file storage or 'DB' for database storage. Returns the created part."
       summary: Create a data part of a Dataset
       requestBody:
         content:
@@ -508,7 +510,7 @@ paths:
         - $ref: '#/components/parameters/size'
       tags:
         - dataset
-      description: "Retrieve all data parts associated with a dataset. Parts can be of type FILE (uploaded files) or DB (database connections). Returns part metadata, type, and status."
+      description: "Retrieve all data parts associated with a dataset."
       summary: Retrieve all dataset parts of a Dataset
       responses:
         "200":
@@ -761,7 +763,7 @@ paths:
       operationId: queryData
       tags:
         - dataset
-      description: "Execute a SQL or DSL query against a database-type dataset part. The query parameter is required. Results are returned as JSON. Only available for parts with type=DB."
+      description: "Execute a query against a dataset part. Results are returned as plain-text CSV. Only available for parts with type=DB."
       summary: |
         Query data of a Dataset part.
         This endpoint is only available for dataset parts that support queries (type == DB).
@@ -792,7 +794,7 @@ paths:
       operationId: downloadDatasetPart
       tags:
         - dataset
-      description: "Download the file content from a FILE-type dataset part. Returns the file as a binary stream with appropriate Content-Type. Not available for DB-type parts."
+      description: "Download the file content from a dataset part. Returns the file as an application/octet-stream."
       summary: Download data from a dataset part
       responses:
         "200":

doc/Apis/DatasetApi.md

@@ -33,7 +33,7 @@ All URIs are relative to *http://localhost:8080*
 
 Create a Dataset
 
-    Create a new dataset in the workspace. Required fields: name. The dataset is initialized with empty data and can be populated through dataset parts. Creator becomes admin.
+    Create a new dataset in the workspace. The dataset is initialized with specified parts (can be empty). The dataset can also be populated through dataset parts.
 
 ### Parameters
 
@@ -91,7 +91,7 @@ Add a control access to the Dataset
 
 Create a data part of a Dataset
 
-    Create a new data part within a dataset. Specify type as 'FILE' for file uploads or 'DB' for database queries. Returns the created part with generated ID.
+    Create a new data part within a dataset. Specify type as 'File' for file storage or 'DB' for database storage. Returns the created part.
 
 ### Parameters
 
@@ -122,7 +122,7 @@ Create a data part of a Dataset
 
 Delete a Dataset
 
-    Permanently delete a dataset and all its data parts. This operation cannot be undone. Returns 204 on success, 404 if not found, 409 if dataset is in use by runners.
+    Permanently delete a dataset and all its data parts. This operation cannot be undone.
 
 ### Parameters
 
@@ -211,7 +211,7 @@ null (empty response body)
 
 Download data from a dataset part
 
-    Download the file content from a FILE-type dataset part. Returns the file as a binary stream with appropriate Content-Type. Not available for DB-type parts.
+    Download the file content from a dataset part. Returns the file as an application/octet-stream.
 
 ### Parameters
 
@@ -241,7 +241,7 @@ Download data from a dataset part
 
 Retrieve a Dataset
 
-    Retrieve complete information about a specific dataset including metadata, source configuration, security settings, and associated dataset parts summary.
+    Retrieve complete information about a specific dataset including dataset parts.
 
 ### Parameters
 
@@ -326,7 +326,7 @@ Retrieve a data part of a Dataset
 
 Retrieve all dataset parts of a Dataset
 
-    Retrieve all data parts associated with a dataset. Parts can be of type FILE (uploaded files) or DB (database connections). Returns part metadata, type, and status.
+    Retrieve all data parts associated with a dataset.
 
 ### Parameters
 
@@ -414,7 +414,7 @@ Retrieve a list of defined Dataset
 
 Query data of a Dataset part. This endpoint is only available for dataset parts that support queries (type == DB). 
 
-    Execute a SQL or DSL query against a database-type dataset part. The query parameter is required. Results are returned as JSON. Only available for parts with type=DB.
+    Execute a query against a dataset part. Results are returned as plain-text CSV. Only available for parts with type=DB.
 
 ### Parameters
 
@@ -543,7 +543,7 @@ Search Datasets by tags
 
 Update a Dataset
 
-    Update dataset metadata (name, description, tags). Note: Some fields cannot be modified after creation. Returns the updated dataset.
+    Update dataset information and return the updated dataset.
 
 ### Parameters
 

doc/Apis/MetaApi.md

@@ -13,7 +13,7 @@ All URIs are relative to *http://localhost:8080*
 
 Get various information about the API
 
-    Retrieve API version information, build details, and platform configuration. Useful for debugging and compatibility checks.
+    Retrieve API version information and build details.
 
 ### Parameters
 This endpoint does not need any parameter.

doc/Apis/OrganizationApi.md

@@ -26,7 +26,7 @@ All URIs are relative to *http://localhost:8080*
 
 Create a new organization
 
-    Create a new organization. Required: name. Optional: security configuration. The creating user automatically becomes an administrator.
+    Create a new organization.
 
 ### Parameters
 
@@ -53,7 +53,7 @@ Create a new organization
 
 Add a control access to the Organization
 
-    Grant access to an organization for a user or group. Valid roles: viewer, editor, admin.
+    Grant access to an organization for a user or group.
 
 ### Parameters
 
@@ -81,7 +81,7 @@ Add a control access to the Organization
 
 Delete an organization
 
-    Permanently delete an organization. Requires all workspaces within the organization to be deleted first. This operation cannot be undone.
+    Permanently delete an organization. This operation cannot be undone.
 
 ### Parameters
 
@@ -134,7 +134,7 @@ null (empty response body)
 
 Get the details of an Organization
 
-    Retrieve detailed information about an organization including name, creation info, update history, and security configuration.
+    Retrieve detailed information about an organization.
 
 ### Parameters
 

doc/Apis/RunApi.md

@@ -45,7 +45,7 @@ null (empty response body)
 
 Get the details of a run
 
-    Retrieve detailed information about a specific run including state, parameters used, dataset list, execution timestamps, and container configuration.
+    Retrieve detailed information about a specific run.
 
 ### Parameters
 
@@ -105,7 +105,7 @@ get the logs for the Run
 
 get the status for the Run
 
-    Retrieve detailed execution status of a run including workflow phase, progress, individual node states, and estimated completion time.
+    Retrieve detailed execution status of a run.
 
 ### Parameters
 
@@ -135,7 +135,7 @@ get the status for the Run
 
 get the list of Runs for the Runner
 
-    Retrieve a paginated list of all runs for a specific runner, ordered by creation time (newest first). Includes run state, timestamps, and basic metadata.
+    Retrieve a paginated list of all runs for a specific runner.
 
 ### Parameters
 

doc/Apis/RunnerApi.md

@@ -27,7 +27,7 @@ All URIs are relative to *http://localhost:8080*
 
 Create a new Runner
 
-    Create a new runner for executing simulations. Required: name, solutionId, runTemplateId. Use parentId to create a child runner that inherits configuration from a parent.
+    Create a new runner for executing simulations. Use parentId to create a child runner that inherits configuration from a parent.
 
 ### Parameters
 
@@ -143,7 +143,7 @@ null (empty response body)
 
 Get the details of a runner
 
-    Retrieve detailed information about a runner including configuration, parameter values, dataset associations, last run status, and validation state.
+    Retrieve detailed information about a runner.
 
 ### Parameters
 
@@ -282,7 +282,7 @@ Get the Runner security users list
 
 List all Runners
 
-    Retrieve a paginated list of all runners in a workspace. Includes master runners and child runners with their current status and configuration.
+    Retrieve a paginated list of all runners in a workspace.
 
 ### Parameters
 
@@ -312,7 +312,7 @@ List all Runners
 
 Start a run with runner parameters
 
-    Start a new simulation run using the runner's current configuration. Returns immediately with a run ID. The run executes asynchronously - use the run status endpoint to monitor progress.
+    Start a new simulation run using the runner's current configuration. Returns the run Id. The run executes asynchronously - use the run status endpoint to monitor progress
 
 ### Parameters
 
@@ -341,7 +341,7 @@ Start a run with runner parameters
 
 Stop the last run
 
-    Stop the currently executing run for this runner. Only affects the most recent run. The stop operation is asynchronous - the run may continue briefly before stopping.
+    Stop the currently executing run for this runner. The stop operation is asynchronous - the run may continue briefly before stopping.
 
 ### Parameters
 

doc/Apis/SolutionApi.md

@@ -39,7 +39,7 @@ All URIs are relative to *http://localhost:8080*
 
 Create a new solution
 
-    Create a new solution with optional run templates and parameter definitions. Required: key (unique identifier), name. The solution key must be unique within the organization.
+    Create a new solution with optional run templates and parameter definitions.
 
 ### Parameters
 
@@ -67,7 +67,7 @@ Create a new solution
 
 Create solution access control
 
-    Grant access to a dataset for a user or group. Required: identity id and role. Valid roles: viewer, editor, admin. Returns 400 if user already has access.
+    Grant access to a solution for a user or group.
 
 ### Parameters
 
@@ -338,7 +338,7 @@ Retrieve a solution run templates
 
 Get the details of a solution
 
-    Retrieve detailed information about a solution including run templates, parameters, parameter groups, and security configuration.
+    Retrieve detailed information about a solution.
 
 ### Parameters
 

doc/Apis/WorkspaceApi.md

@@ -30,7 +30,7 @@ All URIs are relative to *http://localhost:8080*
 
 Create a new workspace
 
-    Create a new workspace linked to a solution. Required: key (unique identifier), name, and solution configuration. The workspace key must be unique within the organization.
+    Create a new workspace.
 
 ### Parameters
 
@@ -58,7 +58,7 @@ Create a new workspace
 
 Add a control access to the Workspace
 
-    Grant access to a workspace for a user or group. Valid roles: viewer, editor, admin. Returns 400 if user already has access.
+    Grant access to a workspace for a user or group.
 
 ### Parameters
 
@@ -87,7 +87,7 @@ Add a control access to the Workspace
 
 Upload a file for the Workspace
 
-    Upload a file to workspace storage. Use 'destination' to specify path, 'overwrite' to replace existing files. Returns 400 if file exists and overwrite is false.
+    Upload a file to workspace storage. Use 'destination' to specify path, 'overwrite' to replace existing files.
 
 ### Parameters
 
@@ -118,7 +118,7 @@ Upload a file for the Workspace
 
 Delete a workspace
 
-    Permanently delete a workspace. All datasets and runners within the workspace must be deleted first. This operation cannot be undone.
+    Permanently delete a workspace.
 
 ### Parameters
 
@@ -228,7 +228,7 @@ null (empty response body)
 
 Get the details of a workspace
 
-    Retrieve detailed information about a workspace including its solution link, security settings, file storage info, and configuration.
+    Retrieve detailed information about a workspace.
 
 ### Parameters
 
@@ -283,7 +283,7 @@ Get a control access for the Workspace
 
 Download the Workspace File specified
 
-    Download a specific file from workspace storage. Requires 'file_name' query parameter. Returns file as binary stream. Returns error if file doesn't exist.
+    Download a specific file from workspace storage. Returns file as binary stream.
 
 ### Parameters
 

meta/src/main/openapi/meta.yaml

@@ -17,7 +17,7 @@ paths:
       operationId: about
       tags:
         - meta
-      description: "Retrieve API version information, build details, and platform configuration. Useful for debugging and compatibility checks."
+      description: "Retrieve API version information and build details."
       summary: Get various information about the API
       responses:
         "200":

organization/src/main/openapi/organization.yaml

@@ -18,7 +18,7 @@ paths:
       operationId: createOrganization
       tags:
         - organization
-      description: "Create a new organization. Required: name. Optional: security configuration. The creating user automatically becomes an administrator."
+      description: "Create a new organization."
       summary: Create a new organization
       requestBody:
         required: true
@@ -90,7 +90,7 @@ paths:
       operationId: getOrganization
       tags:
         - organization
-      description: "Retrieve detailed information about an organization including name, creation info, update history, and security configuration."
+      description: "Retrieve detailed information about an organization."
       summary: Get the details of an Organization
       responses:
         "200":
@@ -155,7 +155,7 @@ paths:
       operationId: deleteOrganization
       tags:
         - organization
-      description: "Permanently delete an organization. Requires all workspaces within the organization to be deleted first. This operation cannot be undone."
+      description: "Permanently delete an organization. This operation cannot be undone."
       summary: Delete an organization
       responses:
         "204":
@@ -302,7 +302,7 @@ paths:
       operationId: createOrganizationAccessControl
       tags:
         - organization
-      description: "Grant access to an organization for a user or group. Valid roles: viewer, editor, admin."
+      description: "Grant access to an organization for a user or group."
       summary: Add a control access to the Organization
       requestBody:
         description: The new Organization security access to add.