From 53f1bbba2b987e2d74ea15e27049940c2c7f0b40 Mon Sep 17 00:00:00 2001 From: Kanita Krasniqi Date: Mon, 1 Sep 2025 00:07:50 +0200 Subject: [PATCH] Update API folder tutorials: YAML, workspace, dataset, solution --- Tutorial/docs/tutorials/api/dataset.md | 133 +++++++++++++++++++++- Tutorial/docs/tutorials/api/solution.md | 128 +++++++++++++++++++++ Tutorial/docs/tutorials/api/workspace.md | 122 ++++++++++++++++++++ Tutorial/docs/tutorials/api/yaml-files.md | 128 ++++++++++++++++++++- 4 files changed, 507 insertions(+), 4 deletions(-) diff --git a/Tutorial/docs/tutorials/api/dataset.md b/Tutorial/docs/tutorials/api/dataset.md index 4255520..f8f8cc3 100644 --- a/Tutorial/docs/tutorials/api/dataset.md +++ b/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 diff --git a/Tutorial/docs/tutorials/api/solution.md b/Tutorial/docs/tutorials/api/solution.md index 72f8f0d..5353ab6 100644 --- a/Tutorial/docs/tutorials/api/solution.md +++ b/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 \ No newline at end of file diff --git a/Tutorial/docs/tutorials/api/workspace.md b/Tutorial/docs/tutorials/api/workspace.md index bb88a5f..8094b36 100644 --- a/Tutorial/docs/tutorials/api/workspace.md +++ b/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 \ No newline at end of file diff --git a/Tutorial/docs/tutorials/api/yaml-files.md b/Tutorial/docs/tutorials/api/yaml-files.md index 7850d35..e611ef6 100644 --- a/Tutorial/docs/tutorials/api/yaml-files.md +++ b/Tutorial/docs/tutorials/api/yaml-files.md @@ -1,3 +1,127 @@ -# Yaml files +# YAML Files -Learn how to structure and use YAML files for API configuration. +!!! info "Tutorial Duration: 15-20 minutes" + +This tutorial covers how to work with **API YAML files** in BuildMyApp. +You'll learn how to define endpoints, configure requests, and integrate them in your Solution, Workspace, and Dataset workflows. + +## Learning Objectives + +By the end of this tutorial, you will understand: + +- The purpose of API YAML files in BuildMyApp +- How to define endpoints, methods, and payloads +- How to test API calls using `curl` or Python +- Best practices for organizing YAML files in a project + +--- + +## What are API YAML Files? + +API YAML files define how your app communicates with the backend. +They contain: + +- **Endpoint URL** +- **HTTP Method** (`GET`, `POST`, `PUT`, `DELETE`) +- **Headers** (authentication, content type) +- **Request Body** (for POST/PUT) +- **Expected Response** + +Think of them as a blueprint for all API calls in your BuildMyApp deployment. + +--- + +## 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 +``` +Using Curl +```bash +curl -X POST "https://api.cosmotech.com/workspaces" \ + -H "Content-Type: application/json" \ + -d '{"name":"MyWorkspace","description":"Example workspace"}' + + +curl -X GET "https://api.cosmotech.com/workspaces" +``` +Using python +``` py +import requests + +# Create workspace +response = requests.post( + "https://api.cosmotech.com/workspaces", + json={"name": "MyWorkspace", "description": "Example workspace"} +) +print(response.json()) + +# List workspaces +response = requests.get("https://api.cosmotech.com/workspaces") +print(response.json()) +``` + + +## Dataset YAML Example + +``` 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} +``` +Using Curl +```bash +curl -X POST "https://api.cosmotech.com/datasets" \ + -H "Content-Type: application/json" \ + -d '{"name":"SampleDataset","description":"Demo dataset"}' + +curl -X GET "https://api.cosmotech.com/datasets/123" +``` + +Using python +```py +import requests + +# Upload dataset +response = requests.post( + "https://api.cosmotech.com/datasets", + json={"name": "SampleDataset", "description": "Demo dataset"} +) +print(response.json()) + +# Get dataset by ID +response = requests.get("https://api.cosmotech.com/datasets/123") +print(response.json()) +``` + +Best Practices + +Keep each resource (workspace, dataset, solution) in its own YAML file + +Use descriptive keys for endpoints (e.g., uploadDataset, listWorkspaces) + +Validate YAML files before committing using tools like yamllint + +Add comments to your YAML files for better maintainability + +Document usage examples alongside each YAML file to make testing easier \ No newline at end of file