From 47c54919605a1ae97f04a9bff4d7b336a6e0e3cb Mon Sep 17 00:00:00 2001 From: Leopold Cramer Date: Wed, 28 Jan 2026 18:12:38 +0100 Subject: [PATCH 1/2] update descriptions for various endpoints --- dataset/src/main/openapi/dataset.yaml | 16 +++++++++------ doc/Apis/DatasetApi.md | 20 +++++++++++++++---- doc/Apis/MetaApi.md | 2 ++ doc/Apis/OrganizationApi.md | 12 ++++++++++- doc/Apis/RunApi.md | 8 ++++++++ doc/Apis/RunnerApi.md | 14 +++++++++++++ doc/Apis/SolutionApi.md | 8 ++++++++ doc/Apis/WorkspaceApi.md | 16 +++++++++++++++ meta/src/main/openapi/meta.yaml | 1 + .../src/main/openapi/organization.yaml | 6 +++++- run/src/main/openapi/run.yaml | 4 ++++ runner/src/main/openapi/runner.yaml | 7 +++++++ solution/src/main/openapi/solution.yaml | 4 ++++ workspace/src/main/openapi/workspace.yaml | 8 ++++++++ 14 files changed, 114 insertions(+), 12 deletions(-) diff --git a/dataset/src/main/openapi/dataset.yaml b/dataset/src/main/openapi/dataset.yaml index 55e6675c3..40a4bdea7 100644 --- a/dataset/src/main/openapi/dataset.yaml +++ b/dataset/src/main/openapi/dataset.yaml @@ -20,11 +20,11 @@ paths: parameters: - $ref: '#/components/parameters/organizationId' - $ref: '#/components/parameters/workspaceId' - description: Create a dataset post: 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." summary: Create a Dataset requestBody: content: @@ -71,7 +71,7 @@ paths: - $ref: '#/components/parameters/size' tags: - dataset - description: List all datasets + description: "Retrieve a paginated list of all datasets in the specified workspace. Supports pagination via 'page' and 'size' query parameters. Returns datasets based on user permissions." summary: Retrieve a list of defined Dataset responses: "200": @@ -166,7 +166,7 @@ paths: operationId: getDataset tags: - dataset - description: Retrieve a dataset + description: "Retrieve complete information about a specific dataset including metadata, source configuration, security settings, and associated dataset parts summary." summary: Retrieve a Dataset responses: "200": @@ -192,7 +192,7 @@ paths: operationId: updateDataset tags: - dataset - description: Update a dataset + description: "Update dataset metadata (name, description, tags). Note: Some fields cannot be modified after creation. Returns the updated dataset." summary: Update a Dataset requestBody: content: @@ -235,7 +235,7 @@ paths: operationId: deleteDataset tags: - dataset - description: Delete a 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." summary: Delete a Dataset responses: "204": @@ -411,6 +411,7 @@ paths: operationId: deleteDatasetAccessControl tags: - dataset + description: "Remove a user or group's access to a dataset. Cannot remove the last administrator - at least one admin must remain." summary: Remove the specified access from the given Dataset responses: "204": @@ -460,9 +461,9 @@ 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." summary: Create a data part of a Dataset requestBody: - description: New Dataset part to create. content: multipart/form-data: schema: @@ -507,6 +508,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." summary: Retrieve all dataset parts of a Dataset responses: "200": @@ -759,6 +761,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." summary: | Query data of a Dataset part. This endpoint is only available for dataset parts that support queries (type == DB). @@ -789,6 +792,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." summary: Download data from a dataset part responses: "200": diff --git a/doc/Apis/DatasetApi.md b/doc/Apis/DatasetApi.md index bfab9a5e4..5fa861a4d 100644 --- a/doc/Apis/DatasetApi.md +++ b/doc/Apis/DatasetApi.md @@ -33,6 +33,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -89,6 +91,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -118,7 +122,7 @@ Create a data part of a Dataset Delete 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. ### Parameters @@ -147,6 +151,8 @@ null (empty response body) Remove the specified access from the given Dataset + Remove a user or group's access to a dataset. Cannot remove the last administrator - at least one admin must remain. + ### Parameters |Name | Type | Description | Notes | @@ -205,6 +211,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -233,7 +241,7 @@ Download data from a dataset part Retrieve a Dataset - Retrieve a dataset + Retrieve complete information about a specific dataset including metadata, source configuration, security settings, and associated dataset parts summary. ### Parameters @@ -318,6 +326,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -374,7 +384,7 @@ Get the Dataset security users list Retrieve a list of defined Dataset - List all datasets + Retrieve a paginated list of all datasets in the specified workspace. Supports pagination via 'page' and 'size' query parameters. Returns datasets based on user permissions. ### Parameters @@ -404,6 +414,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -531,7 +543,7 @@ Search Datasets by tags Update a Dataset - Update a dataset + Update dataset metadata (name, description, tags). Note: Some fields cannot be modified after creation. Returns the updated dataset. ### Parameters diff --git a/doc/Apis/MetaApi.md b/doc/Apis/MetaApi.md index 2d5e55c57..d3ab6b30b 100644 --- a/doc/Apis/MetaApi.md +++ b/doc/Apis/MetaApi.md @@ -13,6 +13,8 @@ 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. + ### Parameters This endpoint does not need any parameter. diff --git a/doc/Apis/OrganizationApi.md b/doc/Apis/OrganizationApi.md index d7b19522e..fa61d6c5f 100644 --- a/doc/Apis/OrganizationApi.md +++ b/doc/Apis/OrganizationApi.md @@ -26,11 +26,13 @@ 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. + ### Parameters |Name | Type | Description | Notes | |------------- | ------------- | ------------- | -------------| -| **OrganizationCreateRequest** | [**OrganizationCreateRequest**](../Models/OrganizationCreateRequest.md)| The Organization to create | | +| **OrganizationCreateRequest** | [**OrganizationCreateRequest**](../Models/OrganizationCreateRequest.md)| | | ### Return type @@ -51,6 +53,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -77,6 +81,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -128,6 +134,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -255,6 +263,8 @@ Get the Organization security users list List all Organizations + Retrieve a paginated list of all organizations the authenticated user has permission to view. Use 'page' and 'size' query parameters for pagination. + ### Parameters |Name | Type | Description | Notes | diff --git a/doc/Apis/RunApi.md b/doc/Apis/RunApi.md index 45493333e..f08c8a7cb 100644 --- a/doc/Apis/RunApi.md +++ b/doc/Apis/RunApi.md @@ -45,6 +45,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -73,6 +75,8 @@ Get the details of a run get the logs for the Run + Retrieve execution logs for a run as plain text. Logs are aggregated from all containers. May be truncated for long-running simulations. + ### Parameters |Name | Type | Description | Notes | @@ -101,6 +105,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -129,6 +135,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | diff --git a/doc/Apis/RunnerApi.md b/doc/Apis/RunnerApi.md index af4db04c8..6136b5619 100644 --- a/doc/Apis/RunnerApi.md +++ b/doc/Apis/RunnerApi.md @@ -27,6 +27,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -54,6 +56,8 @@ Create a new Runner Add a control access to the Runner + Grant access to a runner for a user or group. Valid roles: viewer, editor, validator (can validate runs), admin. + ### Parameters |Name | Type | Description | Notes | @@ -82,6 +86,8 @@ Add a control access to the Runner Delete a runner + Delete a runner. Cannot delete while runs are in progress. Note: Child runners that reference this runner are not deleted automatically. + ### Parameters |Name | Type | Description | Notes | @@ -137,6 +143,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -274,6 +282,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -302,6 +312,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -329,6 +341,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | diff --git a/doc/Apis/SolutionApi.md b/doc/Apis/SolutionApi.md index ac0dae0a6..11cc75557 100644 --- a/doc/Apis/SolutionApi.md +++ b/doc/Apis/SolutionApi.md @@ -39,6 +39,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -65,6 +67,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -334,6 +338,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -571,6 +577,8 @@ List solution security users List all Solutions + Retrieve a paginated list of all solutions in an organization that the user has permission to view. + ### Parameters |Name | Type | Description | Notes | diff --git a/doc/Apis/WorkspaceApi.md b/doc/Apis/WorkspaceApi.md index 4b58c3e6e..6fe3228a5 100644 --- a/doc/Apis/WorkspaceApi.md +++ b/doc/Apis/WorkspaceApi.md @@ -30,6 +30,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -56,6 +58,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -83,6 +87,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -112,6 +118,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -138,6 +146,8 @@ null (empty response body) Remove the specified access from the given Workspace + Remove a user's access to a workspace. Cannot remove the last administrator. + ### Parameters |Name | Type | Description | Notes | @@ -218,6 +228,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -271,6 +283,8 @@ 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. + ### Parameters |Name | Type | Description | Notes | @@ -403,6 +417,8 @@ Get the Workspace security users list List all Workspaces + Retrieve a paginated list of all workspaces in an organization that the user has permission to view. + ### Parameters |Name | Type | Description | Notes | diff --git a/meta/src/main/openapi/meta.yaml b/meta/src/main/openapi/meta.yaml index 4da1cd2ef..d65a59d2c 100644 --- a/meta/src/main/openapi/meta.yaml +++ b/meta/src/main/openapi/meta.yaml @@ -17,6 +17,7 @@ paths: operationId: about tags: - meta + description: "Retrieve API version information, build details, and platform configuration. Useful for debugging and compatibility checks." summary: Get various information about the API responses: "200": diff --git a/organization/src/main/openapi/organization.yaml b/organization/src/main/openapi/organization.yaml index 1959ff7e2..2c84698d5 100644 --- a/organization/src/main/openapi/organization.yaml +++ b/organization/src/main/openapi/organization.yaml @@ -18,9 +18,9 @@ paths: operationId: createOrganization tags: - organization + description: "Create a new organization. Required: name. Optional: security configuration. The creating user automatically becomes an administrator." summary: Create a new organization requestBody: - description: The Organization to create required: true content: application/json: @@ -60,6 +60,7 @@ paths: - $ref: '#/components/parameters/size' tags: - organization + description: "Retrieve a paginated list of all organizations the authenticated user has permission to view. Use 'page' and 'size' query parameters for pagination." summary: List all Organizations responses: "200": @@ -89,6 +90,7 @@ paths: operationId: getOrganization tags: - organization + description: "Retrieve detailed information about an organization including name, creation info, update history, and security configuration." summary: Get the details of an Organization responses: "200": @@ -153,6 +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." summary: Delete an organization responses: "204": @@ -299,6 +302,7 @@ paths: operationId: createOrganizationAccessControl tags: - organization + description: "Grant access to an organization for a user or group. Valid roles: viewer, editor, admin." summary: Add a control access to the Organization requestBody: description: The new Organization security access to add. diff --git a/run/src/main/openapi/run.yaml b/run/src/main/openapi/run.yaml index 41203952b..0fa03df47 100644 --- a/run/src/main/openapi/run.yaml +++ b/run/src/main/openapi/run.yaml @@ -22,6 +22,7 @@ paths: operationId: getRun tags: - run + description: "Retrieve detailed information about a specific run including state, parameters used, dataset list, execution timestamps, and container configuration." summary: Get the details of a run responses: "200": @@ -63,6 +64,7 @@ paths: operationId: getRunStatus tags: - run + description: "Retrieve detailed execution status of a run including workflow phase, progress, individual node states, and estimated completion time." summary: get the status for the Run responses: "200": @@ -90,6 +92,7 @@ paths: operationId: getRunLogs tags: - run + description: "Retrieve execution logs for a run as plain text. Logs are aggregated from all containers. May be truncated for long-running simulations." summary: get the logs for the Run responses: "200": @@ -123,6 +126,7 @@ paths: type: integer tags: - run + description: "Retrieve a paginated list of all runs for a specific runner, ordered by creation time (newest first). Includes run state, timestamps, and basic metadata." summary: get the list of Runs for the Runner responses: "200": diff --git a/runner/src/main/openapi/runner.yaml b/runner/src/main/openapi/runner.yaml index f06572fdb..2f91511aa 100644 --- a/runner/src/main/openapi/runner.yaml +++ b/runner/src/main/openapi/runner.yaml @@ -20,6 +20,7 @@ paths: operationId: createRunner tags: - runner + description: "Create a new runner for executing simulations. Required: name, solutionId, runTemplateId. Use parentId to create a child runner that inherits configuration from a parent." summary: Create a new Runner requestBody: description: the Runner to create @@ -66,6 +67,7 @@ paths: - $ref: '#/components/parameters/size' tags: - runner + description: "Retrieve a paginated list of all runners in a workspace. Includes master runners and child runners with their current status and configuration." summary: List all Runners responses: "200": @@ -97,6 +99,7 @@ paths: operationId: getRunner tags: - runner + description: "Retrieve detailed information about a runner including configuration, parameter values, dataset associations, last run status, and validation state." summary: Get the details of a runner responses: "200": @@ -161,6 +164,7 @@ paths: operationId: deleteRunner tags: - runner + description: "Delete a runner. Cannot delete while runs are in progress. Note: Child runners that reference this runner are not deleted automatically." summary: Delete a runner responses: "204": @@ -177,6 +181,7 @@ paths: operationId: startRun tags: - runner + description: "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." summary: Start a run with runner parameters responses: "202": @@ -200,6 +205,7 @@ paths: operationId: stopRun tags: - runner + description: "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." summary: Stop the last run responses: "202": @@ -333,6 +339,7 @@ paths: operationId: createRunnerAccessControl tags: - runner + description: "Grant access to a runner for a user or group. Valid roles: viewer, editor, validator (can validate runs), admin." summary: Add a control access to the Runner requestBody: description: the new Runner security access to add. diff --git a/solution/src/main/openapi/solution.yaml b/solution/src/main/openapi/solution.yaml index d552937ef..992117571 100644 --- a/solution/src/main/openapi/solution.yaml +++ b/solution/src/main/openapi/solution.yaml @@ -20,6 +20,7 @@ paths: operationId: createSolution tags: - solution + description: "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." summary: Create a new solution requestBody: description: The Solution to create @@ -62,6 +63,7 @@ paths: - $ref: '#/components/parameters/size' tags: - solution + description: "Retrieve a paginated list of all solutions in an organization that the user has permission to view." summary: List all Solutions responses: "200": @@ -92,6 +94,7 @@ paths: operationId: getSolution tags: - solution + description: "Retrieve detailed information about a solution including run templates, parameters, parameter groups, and security configuration." summary: Get the details of a solution responses: "200": @@ -742,6 +745,7 @@ paths: operationId: createSolutionAccessControl tags: - solution + description: "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." summary: Create solution access control requestBody: description: Access control to create diff --git a/workspace/src/main/openapi/workspace.yaml b/workspace/src/main/openapi/workspace.yaml index f4d5d70c7..b0a370391 100644 --- a/workspace/src/main/openapi/workspace.yaml +++ b/workspace/src/main/openapi/workspace.yaml @@ -19,6 +19,7 @@ paths: operationId: createWorkspace tags: - workspace + description: "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." summary: Create a new workspace requestBody: description: The Workspace to create @@ -61,6 +62,7 @@ paths: - $ref: '#/components/parameters/size' tags: - workspace + description: "Retrieve a paginated list of all workspaces in an organization that the user has permission to view." summary: List all Workspaces responses: "200": @@ -90,6 +92,7 @@ paths: operationId: getWorkspace tags: - workspace + description: "Retrieve detailed information about a workspace including its solution link, security settings, file storage info, and configuration." summary: Get the details of a workspace responses: "200": @@ -154,6 +157,7 @@ paths: operationId: deleteWorkspace tags: - workspace + description: "Permanently delete a workspace. All datasets and runners within the workspace must be deleted first. This operation cannot be undone." summary: Delete a workspace responses: "204": @@ -171,6 +175,7 @@ paths: operationId: createWorkspaceFile tags: - workspace + description: "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." summary: Upload a file for the Workspace requestBody: description: The file to upload @@ -275,6 +280,7 @@ paths: operationId: getWorkspaceFile tags: - workspace + description: "Download a specific file from workspace storage. Requires 'file_name' query parameter. Returns file as binary stream. Returns error if file doesn't exist." summary: Download the Workspace File specified responses: "200": @@ -422,6 +428,7 @@ paths: operationId: createWorkspaceAccessControl tags: - workspace + description: "Grant access to a workspace for a user or group. Valid roles: viewer, editor, admin. Returns 400 if user already has access." summary: Add a control access to the Workspace requestBody: description: The new Workspace security access to add. @@ -534,6 +541,7 @@ paths: operationId: deleteWorkspaceAccessControl tags: - workspace + description: "Remove a user's access to a workspace. Cannot remove the last administrator." summary: Remove the specified access from the given Workspace responses: "204": From a2a15fa2337dd6356609c21322921dd8aa7a5a16 Mon Sep 17 00:00:00 2001 From: Leopold Cramer Date: Wed, 4 Feb 2026 10:51:57 +0100 Subject: [PATCH 2/2] apply pr reviews --- dataset/src/main/openapi/dataset.yaml | 18 ++++++++++-------- doc/Apis/DatasetApi.md | 16 ++++++++-------- doc/Apis/MetaApi.md | 2 +- doc/Apis/OrganizationApi.md | 8 ++++---- doc/Apis/RunApi.md | 6 +++--- doc/Apis/RunnerApi.md | 10 +++++----- doc/Apis/SolutionApi.md | 6 +++--- doc/Apis/WorkspaceApi.md | 12 ++++++------ meta/src/main/openapi/meta.yaml | 2 +- .../src/main/openapi/organization.yaml | 8 ++++---- run/src/main/openapi/run.yaml | 6 +++--- runner/src/main/openapi/runner.yaml | 10 +++++----- solution/src/main/openapi/solution.yaml | 6 +++--- workspace/src/main/openapi/workspace.yaml | 12 ++++++------ 14 files changed, 62 insertions(+), 60 deletions(-) diff --git a/dataset/src/main/openapi/dataset.yaml b/dataset/src/main/openapi/dataset.yaml index 40a4bdea7..36b806612 100644 --- a/dataset/src/main/openapi/dataset.yaml +++ b/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": diff --git a/doc/Apis/DatasetApi.md b/doc/Apis/DatasetApi.md index 5fa861a4d..dccff8481 100644 --- a/doc/Apis/DatasetApi.md +++ b/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 diff --git a/doc/Apis/MetaApi.md b/doc/Apis/MetaApi.md index d3ab6b30b..ef2582340 100644 --- a/doc/Apis/MetaApi.md +++ b/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. diff --git a/doc/Apis/OrganizationApi.md b/doc/Apis/OrganizationApi.md index fa61d6c5f..d37263ffb 100644 --- a/doc/Apis/OrganizationApi.md +++ b/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 diff --git a/doc/Apis/RunApi.md b/doc/Apis/RunApi.md index f08c8a7cb..47e971b01 100644 --- a/doc/Apis/RunApi.md +++ b/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 diff --git a/doc/Apis/RunnerApi.md b/doc/Apis/RunnerApi.md index 6136b5619..ffccda65b 100644 --- a/doc/Apis/RunnerApi.md +++ b/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 diff --git a/doc/Apis/SolutionApi.md b/doc/Apis/SolutionApi.md index 11cc75557..d5aaa0fd0 100644 --- a/doc/Apis/SolutionApi.md +++ b/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 diff --git a/doc/Apis/WorkspaceApi.md b/doc/Apis/WorkspaceApi.md index 6fe3228a5..97ff6e37f 100644 --- a/doc/Apis/WorkspaceApi.md +++ b/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 diff --git a/meta/src/main/openapi/meta.yaml b/meta/src/main/openapi/meta.yaml index d65a59d2c..6dd308429 100644 --- a/meta/src/main/openapi/meta.yaml +++ b/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": diff --git a/organization/src/main/openapi/organization.yaml b/organization/src/main/openapi/organization.yaml index 2c84698d5..29df9e7ef 100644 --- a/organization/src/main/openapi/organization.yaml +++ b/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. diff --git a/run/src/main/openapi/run.yaml b/run/src/main/openapi/run.yaml index 0fa03df47..f15aac7ea 100644 --- a/run/src/main/openapi/run.yaml +++ b/run/src/main/openapi/run.yaml @@ -22,7 +22,7 @@ paths: operationId: getRun tags: - run - description: "Retrieve detailed information about a specific run including state, parameters used, dataset list, execution timestamps, and container configuration." + description: "Retrieve detailed information about a specific run." summary: Get the details of a run responses: "200": @@ -64,7 +64,7 @@ paths: operationId: getRunStatus tags: - run - description: "Retrieve detailed execution status of a run including workflow phase, progress, individual node states, and estimated completion time." + description: "Retrieve detailed execution status of a run." summary: get the status for the Run responses: "200": @@ -126,7 +126,7 @@ paths: type: integer tags: - run - description: "Retrieve a paginated list of all runs for a specific runner, ordered by creation time (newest first). Includes run state, timestamps, and basic metadata." + description: "Retrieve a paginated list of all runs for a specific runner." summary: get the list of Runs for the Runner responses: "200": diff --git a/runner/src/main/openapi/runner.yaml b/runner/src/main/openapi/runner.yaml index 2f91511aa..d80562d21 100644 --- a/runner/src/main/openapi/runner.yaml +++ b/runner/src/main/openapi/runner.yaml @@ -20,7 +20,7 @@ paths: operationId: createRunner tags: - runner - description: "Create a new runner for executing simulations. Required: name, solutionId, runTemplateId. Use parentId to create a child runner that inherits configuration from a parent." + description: "Create a new runner for executing simulations. Use parentId to create a child runner that inherits configuration from a parent." summary: Create a new Runner requestBody: description: the Runner to create @@ -67,7 +67,7 @@ paths: - $ref: '#/components/parameters/size' tags: - runner - description: "Retrieve a paginated list of all runners in a workspace. Includes master runners and child runners with their current status and configuration." + description: "Retrieve a paginated list of all runners in a workspace." summary: List all Runners responses: "200": @@ -99,7 +99,7 @@ paths: operationId: getRunner tags: - runner - description: "Retrieve detailed information about a runner including configuration, parameter values, dataset associations, last run status, and validation state." + description: "Retrieve detailed information about a runner." summary: Get the details of a runner responses: "200": @@ -181,7 +181,7 @@ paths: operationId: startRun tags: - runner - description: "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." + description: "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" summary: Start a run with runner parameters responses: "202": @@ -205,7 +205,7 @@ paths: operationId: stopRun tags: - runner - description: "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." + description: "Stop the currently executing run for this runner. The stop operation is asynchronous - the run may continue briefly before stopping." summary: Stop the last run responses: "202": diff --git a/solution/src/main/openapi/solution.yaml b/solution/src/main/openapi/solution.yaml index 992117571..7a2dff023 100644 --- a/solution/src/main/openapi/solution.yaml +++ b/solution/src/main/openapi/solution.yaml @@ -20,7 +20,7 @@ paths: operationId: createSolution tags: - solution - description: "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." + description: "Create a new solution with optional run templates and parameter definitions." summary: Create a new solution requestBody: description: The Solution to create @@ -94,7 +94,7 @@ paths: operationId: getSolution tags: - solution - description: "Retrieve detailed information about a solution including run templates, parameters, parameter groups, and security configuration." + description: "Retrieve detailed information about a solution." summary: Get the details of a solution responses: "200": @@ -745,7 +745,7 @@ paths: operationId: createSolutionAccessControl tags: - solution - description: "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." + description: "Grant access to a solution for a user or group." summary: Create solution access control requestBody: description: Access control to create diff --git a/workspace/src/main/openapi/workspace.yaml b/workspace/src/main/openapi/workspace.yaml index b0a370391..97d0faf7c 100644 --- a/workspace/src/main/openapi/workspace.yaml +++ b/workspace/src/main/openapi/workspace.yaml @@ -19,7 +19,7 @@ paths: operationId: createWorkspace tags: - workspace - description: "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." + description: "Create a new workspace." summary: Create a new workspace requestBody: description: The Workspace to create @@ -92,7 +92,7 @@ paths: operationId: getWorkspace tags: - workspace - description: "Retrieve detailed information about a workspace including its solution link, security settings, file storage info, and configuration." + description: "Retrieve detailed information about a workspace." summary: Get the details of a workspace responses: "200": @@ -157,7 +157,7 @@ paths: operationId: deleteWorkspace tags: - workspace - description: "Permanently delete a workspace. All datasets and runners within the workspace must be deleted first. This operation cannot be undone." + description: "Permanently delete a workspace." summary: Delete a workspace responses: "204": @@ -175,7 +175,7 @@ paths: operationId: createWorkspaceFile tags: - workspace - description: "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." + description: "Upload a file to workspace storage. Use 'destination' to specify path, 'overwrite' to replace existing files." summary: Upload a file for the Workspace requestBody: description: The file to upload @@ -280,7 +280,7 @@ paths: operationId: getWorkspaceFile tags: - workspace - description: "Download a specific file from workspace storage. Requires 'file_name' query parameter. Returns file as binary stream. Returns error if file doesn't exist." + description: "Download a specific file from workspace storage. Returns file as binary stream." summary: Download the Workspace File specified responses: "200": @@ -428,7 +428,7 @@ paths: operationId: createWorkspaceAccessControl tags: - workspace - description: "Grant access to a workspace for a user or group. Valid roles: viewer, editor, admin. Returns 400 if user already has access." + description: "Grant access to a workspace for a user or group." summary: Add a control access to the Workspace requestBody: description: The new Workspace security access to add.