Update API folder tutorials: YAML, workspace, dataset, solution

Tutorial/docs/tutorials/api/dataset.md

@@ -1,3 +1,132 @@
-# Dataset
+# Dataset Management
 
-Datasets and data management through the CosmoTech API.
+Learn how to manage datasets in BuildMyApp using the API and YAML files.
+
+!!! info "Tutorial Duration: 15-25 minutes"
+
+This tutorial covers dataset creation, retrieval, updating, and best practices for managing datasets in your deployment.
+
+---
+
+## Learning Objectives
+
+By the end of this tutorial, you will understand:
+
+- How to upload, retrieve, update, and delete datasets via API  
+- How to structure dataset YAML files  
+- How to test dataset endpoints using curl and Python  
+- Best practices for dataset naming and organization  
+
+---
+
+## Understanding Datasets
+
+Datasets are structured collections of data used in your BuildMyApp solution.  
+
+Each dataset includes:
+
+- **Name**: Unique identifier for the dataset  
+- **Description**: Short description of the dataset content  
+- **Data files**: CSV, JSON, or other supported formats  
+- **Metadata**: Optional fields for additional information  
+
+Datasets allow solutions and simulations to process data efficiently and reproducibly.
+
+---
+
+## Dataset YAML Example
+
+```yaml title="dataset.yaml"
+dataset:
+  upload:
+    method: POST
+    url: /datasets
+    headers:
+      Content-Type: application/json
+    body:
+      name: SampleDataset
+      description: "Demo dataset for testing"
+  get:
+    method: GET
+    url: /datasets/{id}
+  update:
+    method: PUT
+    url: /datasets/{id}
+    headers:
+      Content-Type: application/json
+    body:
+      name: UpdatedDataset
+      description: "Updated description"
+  delete:
+    method: DELETE
+    url: /datasets/{id}
+ ```
+
+### Upload Dataset
+
+Using curl
+```bash
+    curl -X POST "https://api.cosmotech.com/datasets" \
+     -H "Content-Type: application/json" \
+     -d '{"name":"SampleDataset","description":"Demo dataset"}'
+```
+Using python
+```py
+import requests
+
+response = requests.post(
+    "https://api.cosmotech.com/datasets",
+    json={"name": "SampleDataset", "description": "Demo dataset"}
+)
+print(response.json())
+
+```
+### Retrieve dataset
+
+Using curl
+```bash
+curl -X GET "https://api.cosmotech.com/datasets/123"
+```
+Using python
+```py
+response = requests.get("https://api.cosmotech.com/datasets/123")
+print(response.json())
+```
+### Update dataset
+
+Using curl
+```bash
+curl -X PUT "https://api.cosmotech.com/datasets/123" \
+     -H "Content-Type: application/json" \
+     -d '{"name":"UpdatedDataset","description":"Updated description"}'
+```
+Using python
+```py
+response = requests.put(
+    "https://api.cosmotech.com/datasets/123",
+    json={"name": "UpdatedDataset", "description": "Updated description"}
+)
+print(response.json())
+```
+### Delete dataset
+
+Using curl 
+```bash
+curl -X DELETE "https://api.cosmotech.com/datasets/123"
+```
+Using python
+```py
+response = requests.delete("https://api.cosmotech.com/datasets/123")
+print(response.status_code)  # 204 means deleted successfully
+```
+## Best practices
+
+Use descriptive names for datasets (e.g., CustomerData2025, not just Dataset1)
+
+Keep YAML files version-controlled for reproducibility
+
+Validate your YAML files with yamllint before deploying
+
+Avoid overwriting datasets unnecessarily — prefer creating new versions
+
+Always test with small datasets before uploading large production data

Tutorial/docs/tutorials/api/solution.md

@@ -1,3 +1,131 @@
 # Solution
 
 Manage solutions through the CosmoTech API.
+
+!!! info "Tutorial Duration: 15-20 minutes"
+
+This tutorial covers solution creation, retrieval, updating, and deletion, as well as best practices for managing solutions in your deployment.
+
+---
+
+## Learning Objectives
+
+By the end of this tutorial, you will understand:
+
+- How to create, retrieve, update, and delete solutions via API  
+- How to structure solution YAML files  
+- How to test solution endpoints using curl and Python  
+- Best practices for solution naming and organization  
+
+---
+
+## Understanding Solutions
+
+Solutions are the core deployments in BuildMyApp. They combine datasets, workflows, and configurations to perform simulations or analyses.
+
+Each solution includes:
+
+- **Name**: Unique identifier for the solution  
+- **Description**: Short description of what the solution does  
+- **Workspace**: Workspace to which the solution belongs  
+- **Configuration**: Optional metadata or simulation parameters  
+
+---
+
+## Solution YAML Example
+
+```yaml title="solution.yaml"
+solution:
+  create:
+    method: POST
+    url: /solutions
+    headers:
+      Content-Type: application/json
+    body:
+      name: MySolution
+      description: "Example solution for deployment"
+      workspaceId: 123
+  list:
+    method: GET
+    url: /solutions
+  update:
+    method: PUT
+    url: /solutions/{id}
+    headers:
+      Content-Type: application/json
+    body:
+      name: UpdatedSolution
+      description: "Updated solution description"
+  delete:
+    method: DELETE
+    url: /solutions/{id}
+```
+### Create Solution
+
+Using curl
+```bash
+curl -X POST "https://api.cosmotech.com/solutions" \
+     -H "Content-Type: application/json" \
+     -d '{"name":"MySolution","description":"Example solution for deployment","workspaceId":123}'
+```
+Using python
+```py
+import requests
+
+response = requests.post(
+    "https://api.cosmotech.com/solutions",
+    json={"name": "MySolution", "description": "Example solution for deployment", "workspaceId": 123}
+)
+print(response.json())
+```
+
+### List Solutions
+
+Using curl
+```bash
+curl -X GET "https://api.cosmotech.com/solutions"
+```
+Using python
+```py
+response = requests.get("https://api.cosmotech.com/solutions")
+print(response.json())
+```
+
+### Update Solution
+
+Using curl
+```bash
+curl -X PUT "https://api.cosmotech.com/solutions/456" \
+     -H "Content-Type: application/json" \
+     -d '{"name":"UpdatedSolution","description":"Updated solution description"}'
+```
+Using python
+```py
+response = requests.put(
+    "https://api.cosmotech.com/solutions/456",
+    json={"name": "UpdatedSolution", "description": "Updated solution description"}
+)
+print(response.json())
+```
+### Delete Soultions
+
+Using curl
+```bash
+curl -X DELETE "https://api.cosmotech.com/solutions/456"
+```
+Using python
+```py
+response = requests.delete("https://api.cosmotech.com/solutions/456")
+print(response.status_code)  # 204 means deleted successfully
+```
+
+## Best Practices
+Use descriptive names for solutions (e.g., CustomerAnalysis2025)
+
+Keep YAML files version-controlled for reproducibility
+
+Validate YAML files with yamllint before deploying
+
+Organize solutions within workspaces for clarity
+
+Test solutions with small datasets before running full simulations

Tutorial/docs/tutorials/api/workspace.md

@@ -1,3 +1,125 @@
 # Workspace
 
 Workspaces and their management via the CosmoTech API.
+
+!!! info "Tutorial Duration: 15-20 minutes"
+
+This tutorial covers workspace creation, retrieval, updating, and deletion, and best practices for managing workspaces in your deployment.
+
+---
+
+## Learning Objectives
+
+By the end of this tutorial, you will understand:
+
+- How to create, retrieve, update, and delete workspaces via API  
+- How to structure workspace YAML files  
+- How to test workspace endpoints using curl and Python  
+- Best practices for workspace naming and organization  
+
+---
+
+## Understanding Workspaces
+
+Workspaces are containers for your solutions, datasets, and simulations. They help organize your deployment and control access to resources.
+
+Each workspace includes:
+
+- **Name**: Unique identifier for the workspace  
+- **Description**: Short description of the workspace  
+- **Permissions**: Access control for users and roles  
+
+---
+
+## Workspace YAML Example
+
+```yaml title="workspace.yaml"
+workspace:
+  create:
+    method: POST
+    url: /workspaces
+    headers:
+      Content-Type: application/json
+    body:
+      name: MyWorkspace
+      description: "Example workspace for deployment"
+  list:
+    method: GET
+    url: /workspaces
+  update:
+    method: PUT
+    url: /workspaces/{id}
+    headers:
+      Content-Type: application/json
+    body:
+      name: UpdatedWorkspace
+      description: "Updated workspace description"
+  delete:
+    method: DELETE
+    url: /workspaces/{id}
+```
+
+### Create Workspace
+
+Using Curl
+```bash
+curl -X POST "https://api.cosmotech.com/workspaces" \
+     -H "Content-Type: application/json" \
+     -d '{"name":"MyWorkspace","description":"Example workspace for deployment"}'
+```
+Using python
+```py
+import requests
+
+response = requests.post(
+    "https://api.cosmotech.com/workspaces",
+    json={"name": "MyWorkspace", "description": "Example workspace for deployment"}
+)
+print(response.json())
+```
+### List Workspaces
+
+Using curl
+```bash
+curl -X GET "https://api.cosmotech.com/workspaces"
+```
+Using python
+```py
+response = requests.get("https://api.cosmotech.com/workspaces")
+print(response.json())
+```
+### Update Workspace
+Using curl
+```bash
+curl -X PUT "https://api.cosmotech.com/workspaces/123" \
+     -H "Content-Type: application/json" \
+     -d '{"name":"UpdatedWorkspace","description":"Updated workspace description"}'
+```
+Using python
+```py
+response = requests.put(
+    "https://api.cosmotech.com/workspaces/123",
+    json={"name": "UpdatedWorkspace", "description": "Updated workspace description"}
+)
+print(response.json())
+```
+### Delete Workspace
+Using curl
+```bash
+curl -X DELETE "https://api.cosmotech.com/workspaces/123"
+```
+Using python
+```py
+response = requests.delete("https://api.cosmotech.com/workspaces/123")
+print(response.status_code)  # 204 means deleted successfully
+```
+## Best Practices
+Use descriptive names for workspaces (e.g., Marketing2025, not just Workspace1)
+
+Keep YAML files version-controlled for reproducibility
+
+Validate YAML files with yamllint before deploying
+
+Avoid deleting workspaces unless necessary; prefer archiving or renaming
+
+Organize workspaces by team, project, or environment for clarity