APIs cookbook

# These examples are adapted from the SysML v2 API Cookbook, available at
# https://github.com/Systems-Modeling/SysML-v2-API-Cookbook, maintained by the
# Object Management Group (OMG).
# The original cookbook is designed for use with Jupyter Lab.
# These examples have been adapted to run as standalone Python scripts, making
# them suitable for use in various environments, including SysON.
# They showcase practical usage scenarios and may include additional functionality
# or modifications tailored to specific needs.

import requests (1)
from init_api import init_sysmlv2_api

def fetch_projects(host): (2)
    projects_url = f"{host}/projects" (3)
    response = requests.get(projects_url) (4)
    if response.status_code == 200: (5)
        projects = response.json()
        for project in projects:
            print(f"Project Name: {project['name']}, ID: {project['@id']}")
    else:
        print(f"Error fetching projects: {response.status_code} - {response.text}")

if __name__ == "__main__":
    host = init_sysmlv2_api()
    # Get the projects
    fetch_projects(host)

$ python fetch_projects.py

Project Name: Batmobile, ID: 63a03bd8-a81a-4818-801a-01790ce8a086

# These examples are adapted from the SysML v2 API Cookbook, available at
# https://github.com/Systems-Modeling/SysML-v2-API-Cookbook, maintained by the
# Object Management Group (OMG).
# The original cookbook is designed for use with Jupyter Lab.
# These examples have been adapted to run as standalone Python scripts, making
# them suitable for use in various environments, including SysON.
# They showcase practical usage scenarios and may include additional functionality
# or modifications tailored to specific needs.

import requests (1)
from init_api import init_sysmlv2_api
from fetch_projects import fetch_projects
from datetime import datetime

def create_project(host, project_name): (2)
    # Define project data as query parameters
    project_params = {
        "name": project_name
    }

    # API endpoint to create a project
    url = f"{host}/projects"  (3)

    # Send POST request with query parameters
    response = requests.post(url, params=project_params)  (4)

    # Check if the project creation was successful
    if response.status_code == 201:  (5)
        response_json = response.json()
        print("Project created successfully:")
        print(f"Project ID: {response_json.get("@id", "Unknown ID")}")
        print(f"Project Name: {response_json.get('name', 'Unknown Name')}")
    else:
        print(f"Error creating project: {response.status_code} - {response.text}")

if __name__ == "__main__":
    host = init_sysmlv2_api()

    # Fetch and display the list of projects currently available on the server
    print("Fetching the list of projects currently available on the server:")
    fetch_projects(host)

    # Create a new project with a unique name by appending a timestamp
    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    project_name = f"New Project - {timestamp}"
    create_project(host, project_name)

    # Fetch and display the updated list of projects after creating the new project
    print("Fetching the updated list of projects after creating a new project:")
    fetch_projects(host)

$ python create_project.py

Fetching the list of projects currently available on the server:
Project Name: Batmobile, ID: 63a03bd8-a81a-4818-801a-01790ce8a086
Project created successfully:
Project ID: d967b937-304f-43a9-8af6-b1f3a9d6adbe
Project Name: New Project - 2024-12-31 10:52:56
Fetching the updated list of projects after creating a new project:
Project Name: Batmobile, ID: 63a03bd8-a81a-4818-801a-01790ce8a086
Project Name: New Project - 2024-12-31 10:52:56, ID: d967b937-304f-43a9-8af6-b1f3a9d6adbe

# These examples are adapted from the SysML v2 API Cookbook, available at
# https://github.com/Systems-Modeling/SysML-v2-API-Cookbook, maintained by the
# Object Management Group (OMG).
# The original cookbook is designed for use with Jupyter Lab.
# These examples have been adapted to run as standalone Python scripts, making
# them suitable for use in various environments, including SysON.
# They showcase practical usage scenarios and may include additional functionality
# or modifications tailored to specific needs.

import requests (1)
from init_api import parse_arguments
from init_api import init_sysmlv2_api

def fetch_commits(host, project_id):  (2)
    commits_url = f"{host}/projects/{project_id}/commits"  (3)
    response = requests.get(commits_url)  (4)
    if response.status_code == 200:  (5)
        commits = response.json()
        for commit in commits:
            print(f"Commit ID: {commit['@id']}")
        return commits
    else:
        print(f"Error fetching commits: {response.status_code} - {response.text}")
        return None

#  Retrieves the latest commit for a given project.
def get_last_commit_id(host, project_id):
    commits = fetch_commits(host, project_id)
    if commits:
        last_commit = commits[-1] if commits else None
        if last_commit:
            last_commit_id = last_commit['@id']
            print(f"Last Commit ID: {last_commit_id}")
        return last_commit_id
    else:
        print("No commits available.")
        return None

if __name__ == "__main__":
    args = parse_arguments()
    host = init_sysmlv2_api()
    project_id = args.project_id
    fetch_commits(host, project_id)

$ python fetch_commits.py your-project-id

Commit ID: 63a03bd8-a81a-4818-801a-01790ce8a086

# These examples are adapted from the SysML v2 API Cookbook, available at
# https://github.com/Systems-Modeling/SysML-v2-API-Cookbook, maintained by the
# Object Management Group (OMG).
# The original cookbook is designed for use with Jupyter Lab.
# These examples have been adapted to run as standalone Python scripts, making
# them suitable for use in various environments, including SysON.
# They showcase practical usage scenarios and may include additional functionality
# or modifications tailored to specific needs.

import requests
from init_api import parse_arguments
from init_api import init_sysmlv2_api
from fetch_commits import get_last_commit_id

# Function to fetch an element and print its name and type
def get_element(host, project_id, commit_id, element_id, indent):
     # Fetch the element in the given commit of the given project
    element_url = f"{host}/projects/{project_id}/commits/{commit_id}/elements/{element_id}"  (3)
    response = requests.get(element_url)  (1)

    if response.status_code == 200:
        element_data = response.json()
        element_name_to_print = element_data['name'] if element_data['name'] else 'N/A'
        element_id = element_data ['@id']
        element_type = element_data ['@type']
        print(f"{indent} - {element_name_to_print} (id = {element_id} , type = {element_type})") (2)
        return element_data
    else:
        return None

# Fetches immediate owned elements for a given element
def get_owned_elements_immediate(host, project_id, commit_id, element_id, indent):
    element_data = get_element(host, project_id, commit_id, element_id, indent)
    if element_data:
        owned_elements = element_data['ownedElement']
        if len(owned_elements) > 0:
            for owned_element in owned_elements:
                get_element(host, project_id, commit_id, owned_element['@id'], indent + '  ')
    else:
        print(f"Unable to fetch element with id '{element_id}' in commit '{commit_id}' of project '{project_id}'")

# Fetches owned elements recursively for a given element
def get_owned_elements(host, project_id, commit_id, element_id, indent):
    element_data = get_element(host, project_id, commit_id, element_id, indent)
    if element_data: (3)
        owned_elements = element_data['ownedElement']
        if len(owned_elements) > 0:
            for owned_element in owned_elements:
                get_owned_elements(host, project_id, commit_id, owned_element['@id'], indent+' ')
    else:
        print(f"Unable to fetch element with id '{element_id}' in commit '{commit_id}' of project '{project_id}'")  (4)

if __name__ == "__main__":
    args = parse_arguments()
    host = init_sysmlv2_api()
    project_id = args.project_id
    commit_id = get_last_commit_id(host, project_id)
    element_id = args.element_id

    #Get owned elements (immediate) for the given element in the given commit of the given project
    print("Immediate Owned Elements:")
    get_owned_elements_immediate(host, project_id, commit_id, element_id, '')

    # Get owned elements (recursive) for the given element in the given commit of the given project
    print("\nRecursive Owned Elements:")
    get_owned_elements(host, project_id, commit_id, element_id, '')

$ python get_owned_elements.py your-project-id your-element-id

Commit ID: 63a03bd8-a81a-4818-801a-01790ce8a086
Last Commit ID: 63a03bd8-a81a-4818-801a-01790ce8a086
Immediate Owned Elements:
 - Batmobile (Definition)
   - problemStatement (ReferenceUsage)
   - systemIdea (ReferenceUsage)
   - seat (PartUsage)
   - body (PartUsage)
   - wheels (PartUsage)
   - frontLeftWheel (PartUsage)
   - frontRightWheel (PartUsage)
   - rearLeftWheel (PartUsage)
   - rearRightWheel (PartUsage)
   - battery (PartUsage)
   - batmobileEngine (PartUsage)

Recursive Owned Elements:
 - Batmobile (Definition)
  - problemStatement (ReferenceUsage)
   - N/A (LiteralString)
  - systemIdea (ReferenceUsage)
   - N/A (LiteralString)
  - seat (PartUsage)
  - body (PartUsage)
  - wheels (PartUsage)
  - frontLeftWheel (PartUsage)
  - frontRightWheel (PartUsage)
  - rearLeftWheel (PartUsage)
  - rearRightWheel (PartUsage)
  - battery (PartUsage)
   - powerPort (PortUsage)
   - capacity (AttributeUsage)
  - batmobileEngine (PartUsage)
   - enginePort (PortUsage)

###############################################################################
# Copyright (c) 2025 Obeo.
# This program and the accompanying materials
# are made available under the terms of the Eclipse Public License v2.0
# which accompanies this distribution, and is available at
# https://www.eclipse.org/legal/epl-2.0/
#
# SPDX-License-Identifier: EPL-2.0
#
# Contributors:
#     Obeo - initial API and implementation
###############################################################################

import requests (1)
import uuid
import argparse
from pathlib import Path

headers = {
    "Content-Type": "application/json"
}

GRAPHQL_ENDPOINT =  "/api/graphql"

# GraphQL query to fetch editing context and stereotypes
fetch_editing_context_query = """
query FetchEditingContext($projectId: ID!) {
  viewer {
    project(projectId: $projectId) {
      currentEditingContext {
        id
        stereotypes {
          edges {
            node {
              id
              label
            }
          }
        }
      }
    }
  }
}
"""

# GraphQL mutation for importing SysML v2 content
import_sysml_mutation = """
mutation InsertTextualSysMLv2($input: InsertTextualSysMLv2Input!) {
  insertTextualSysMLv2(input: $input) {
    __typename
    ... on SuccessPayload {
      id
    }
    ... on ErrorPayload {
      message
    }
  }
}
"""

# Function to fetch the editing context
def fetch_editing_context(url, project_id): (2)
    graphql_url = f"{url}{GRAPHQL_ENDPOINT}"
    variables = {"projectId": project_id}
    response = requests.post(
        graphql_url,
        json={"query": fetch_editing_context_query, "variables": variables},
        headers=headers
    )

    if response.status_code != 200:
        print(f"Error fetching editing context: {response.status_code} - {response.text}")
        return None

    data = response.json()
    viewer = data.get("data", {}).get("viewer", {})
    project = viewer.get("project", {})
    editing_context = project.get("currentEditingContext", {})
    return editing_context

# Function to import SysML v2 content into a project
def import_sysml_to_project(url, file_path, editing_context_id, object_id): (3)
    graphql_url = f"{url}{GRAPHQL_ENDPOINT}"
    try:
        # Read the SysML v2 file
        with open(file_path, "r") as file:
            textual_content = file.read()

        # Generate a unique operation ID
        operation_id = str(uuid.uuid4())

        # Prepare mutation variables
        variables = {
            "input": {
                "id": operation_id,
                "editingContextId": editing_context_id,
                "objectId": object_id,
                "textualContent": textual_content
            }
        }

        # Send the mutation request (4)
        response = requests.post(
            graphql_url,
            json={"query": import_sysml_mutation, "variables": variables},
            headers= headers
        )

        if response.status_code != 200:
            print(f"Error importing SysML v2: {response.status_code} - {response.text}")
            return False

        data = response.json()
        result = data.get("data", {}).get("insertTextualSysMLv2", {})

        if result.get("__typename") == "SuccessPayload":
            return True
        elif result.get("__typename") == "ErrorPayload":
            print(f"Error: {result.get('message')}")
            return False
        else:
            print("Unexpected response:", data)
            return False

    except Exception as e:
        print(f"An error occurred while importing SysML v2: {e}")
        return False

if __name__ == "__main__":
    # Set up argument parsing
    parser = argparse.ArgumentParser(description="SysON new objects from text script")

    parser.add_argument(
        "url",
        nargs="?",  # Makes the argument optional
        default="http://localhost:8080",  # Default value
        help="The API base URL (e.g., http://yourSysonServerURL). Defaults to http://localhost:8080"
    )

    parser.add_argument(
        "file_path",
        type=Path,  # Ensure it's a valid path
        help="File path containing the SysML textual file to import (absolute path required)"
    )

    parser.add_argument(
        "project_id",
        type=str,
        help="The UUID of the project to import the SysML file into"
    )

    parser.add_argument(
        "namespace_elementId",
        type=str,
        help="The elementId of the SysMLv2 element under which the content of the SysMLv2 file will be imported"
    )

    args = parser.parse_args()

    # Get all function parameters (5)
    url = args.url
    file_path = args.file_path
    # Fetch editing context
    editing_context = fetch_editing_context(url, args.project_id)
    if editing_context:
        editing_context_id = editing_context["id"]
    else:
        print("Editing context not found.")
        exit()
    namespace_id = args.namespace_elementId

    # Import SysML file into the project, under the specified Namespace element
    if import_sysml_to_project(url, file_path, editing_context_id, namespace_id): (6)
        print(f"SysML v2 file imported successfully: {file_path}") (7)
    else:
        print(f"Failed to import SysML v2 file: {file_path}") (7)

$ python new_objects_from_text.py url-of-syson-server file-path-of-sysmlv2-file your-project-id your-namespace-elementId

$ python new_objects_from_text.py http://localhost:8080 /Users/myUserFolder/myFolder/mySysMLv2File.sysml 76bb3f29-17d1-465a-a2ca-a331978c36f3 2c0ddeb4-b9fe-478e-951e-0ca312013a5b

SysML v2 file imported successfully: /Users/myUserFolder/myFolder/mySysMLv2File.sysml

###############################################################################
# Copyright (c) 2026 Obeo.
# This program and the accompanying materials
# are made available under the terms of the Eclipse Public License v2.0
# which accompanies this distribution, and is available at
# https://www.eclipse.org/legal/epl-2.0/
#
# SPDX-License-Identifier: EPL-2.0
#
# Contributors:
#     Obeo - initial API and implementation
###############################################################################

import argparse
import json
import uuid
from pathlib import Path

import requests  (1)


GRAPHQL_ENDPOINT = "/api/graphql"
GRAPHQL_UPLOAD_ENDPOINT = "/api/graphql/upload"


fetch_editing_context_query = """
query FetchEditingContext($projectId: ID!) {
  viewer {
    project(projectId: $projectId) {
      currentEditingContext {
        id
      }
    }
  }
}
"""


upload_document_mutation = """
mutation UploadDocument($input: UploadDocumentInput!) {
  uploadDocument(input: $input) {
    __typename
    ... on UploadDocumentSuccessPayload {
      id
      report
    }
    ... on ErrorPayload {
      messages {
        body
        level
      }
    }
  }
}
"""


def get_graphql_url(url):
    return f"{url.rstrip('/')}{GRAPHQL_ENDPOINT}"


def get_graphql_upload_url(url):
    return f"{url.rstrip('/')}{GRAPHQL_UPLOAD_ENDPOINT}"


def print_graphql_errors(data):
    errors = data.get("errors", [])
    for error in errors:
        print(f"GraphQL error: {error.get('message', error)}")


def fetch_editing_context_id(url, project_id):  (2)
    response = requests.post(
        get_graphql_url(url),
        json={
            "query": fetch_editing_context_query,
            "variables": {"projectId": project_id},
        },
    )

    if response.status_code != 200:
        print(f"Error fetching editing context: {response.status_code} - {response.text}")
        return None

    data = response.json()
    if data.get("errors"):
        print_graphql_errors(data)
        return None

    project = data.get("data", {}).get("viewer", {}).get("project")
    if not project:
        print(f"Project not found: {project_id}")
        return None

    editing_context = project.get("currentEditingContext")
    if not editing_context:
        print(f"Editing context not found for project: {project_id}")
        return None

    return editing_context.get("id")


def print_messages(messages):
    for message in messages:
        print(f"{message.get('level', 'INFO')}: {message.get('body', '')}")


def import_sysml_file(url, file_path, editing_context_id, read_only):  (3)
    operation_id = str(uuid.uuid4())
    operations = {
        "query": upload_document_mutation,
        "variables": {
            "input": {
                "id": operation_id,
                "editingContextId": editing_context_id,
                "file": None,
                "readOnly": read_only,
            }
        },
    }
    file_map = {
        "0": "variables.file"
    }

    with open(file_path, "rb") as file:
        response = requests.post(  (4)
            get_graphql_upload_url(url),
            data={
                "operations": json.dumps(operations),
                "map": json.dumps(file_map),
            },
            files={
                "0": (file_path.name, file, "text/plain"),
            },
        )

    if response.status_code not in (200, 201):
        print(f"Error importing SysML file: {response.status_code} - {response.text}")
        return False

    data = response.json()
    if data.get("errors"):
        print_graphql_errors(data)
        return False

    payload = data.get("data", {}).get("uploadDocument", {})
    if payload.get("__typename") == "UploadDocumentSuccessPayload":
        print(f"SysML file imported successfully: {file_path}")
        report = payload.get("report")
        if report:
            print("Import report:")
            print(report)
        return True

    if payload.get("__typename") == "ErrorPayload":
        print_messages(payload.get("messages", []))
        return False

    print(f"Unexpected response: {data}")
    return False


def parse_arguments():
    parser = argparse.ArgumentParser(description="Import a SysML textual file into a SysON project")
    parser.add_argument(
        "arguments",
        nargs="+",
        help="Either: file-path project-id, or: url file-path project-id",
    )
    parser.add_argument(
        "--read-only",
        action="store_true",
        help="Import the uploaded document as read-only",
    )
    args = parser.parse_args()

    if len(args.arguments) == 2:
        args.url = "http://localhost:8080"
        args.file_path = Path(args.arguments[0])
        args.project_id = args.arguments[1]
    elif len(args.arguments) == 3:
        args.url = args.arguments[0]
        args.file_path = Path(args.arguments[1])
        args.project_id = args.arguments[2]
    else:
        parser.error("expected either: file-path project-id, or: url file-path project-id")

    return args


if __name__ == "__main__":
    args = parse_arguments()
    file_path = args.file_path.expanduser().resolve()

    if not file_path.is_file():
        print(f"File not found: {file_path}")
        exit(1)

    editing_context_id = fetch_editing_context_id(args.url, args.project_id)  (5)
    if not editing_context_id:
        exit(1)

    if not import_sysml_file(args.url, file_path, editing_context_id, args.read_only):  (6)
        exit(1)

$ python import_sysml_file.py file-path-of-sysml-file your-project-id
$ python import_sysml_file.py url-of-syson-server file-path-of-sysml-file your-project-id

$ python import_sysml_file.py /Users/myUserFolder/myFolder/mySysMLv2File.sysml 76bb3f29-17d1-465a-a2ca-a331978c36f3

SysML file imported successfully: /Users/myUserFolder/myFolder/mySysMLv2File.sysml

###############################################################################
# Copyright (c) 2026 Obeo.
# This program and the accompanying materials
# are made available under the terms of the Eclipse Public License v2.0
# which accompanies this distribution, and is available at
# https://www.eclipse.org/legal/epl-2.0/
#
# SPDX-License-Identifier: EPL-2.0
#
# Contributors:
#     Obeo - initial API and implementation
###############################################################################

import argparse
import io
import json
import zipfile

import requests  (1)


PROJECT_DOWNLOAD_ENDPOINT = "/api/projects/{project_id}"


def get_project_download_url(url, project_id):
    return f"{url.rstrip('/')}{PROJECT_DOWNLOAD_ENDPOINT.format(project_id=project_id)}"


def download_project_archive(url, project_id):  (2)
    response = requests.get(
        get_project_download_url(url, project_id),  (3)
        stream=True,
    )

    if response.status_code != 200:
        print(f"Error downloading project archive: {response.status_code} - {response.text}")
        return None

    archive_content = io.BytesIO()
    for chunk in response.iter_content(chunk_size=8192):
        if chunk:
            archive_content.write(chunk)

    archive_content.seek(0)
    with zipfile.ZipFile(archive_content) as archive:
        manifest_name = None
        for entry_name in archive.namelist():
            if entry_name.endswith("/manifest.json"):
                manifest_name = entry_name
                break

        if not manifest_name:
            print("manifest.json not found in the project archive")
            return None

        with archive.open(manifest_name) as manifest_file:
            manifest = json.load(io.TextIOWrapper(manifest_file, encoding="utf-8"))  (4)

    document_ids_to_name = manifest.get("documentIdsToName", {})
    if not document_ids_to_name:
        print("No documents found in the project manifest")
        return []

    documents = sorted(document_ids_to_name.items(), key=lambda item: item[1].lower())
    return documents


def parse_arguments():
    parser = argparse.ArgumentParser(description="Retrieve the documents of a SysON project")
    parser.add_argument(
        "arguments",
        nargs="+",
        help="Either: project-id, or: url project-id",
    )
    args = parser.parse_args()

    if len(args.arguments) == 1:
        args.url = "http://localhost:8080"
        args.project_id = args.arguments[0]
    elif len(args.arguments) == 2:
        args.url = args.arguments[0]
        args.project_id = args.arguments[1]
    else:
        parser.error("expected either: project-id, or: url project-id")

    return args


if __name__ == "__main__":
    args = parse_arguments()
    documents = download_project_archive(args.url, args.project_id)

    if documents is None:
        raise SystemExit(1)

    for document_id, document_name in documents:  (5)
        print(f"Document Name: {document_name}, Document ID: {document_id}")

$ python retrieve_project_documents.py project-id
$ python retrieve_project_documents.py url-of-syson-server project-id

$ python retrieve_project_documents.py 76bb3f29-17d1-465a-a2ca-a331978c36f3

Document Name: SysMLv2.sysml, Document ID: 3cb6f3b1-8a10-41b7-9a08-d32b66e28c6f
Document Name: Requirements.sysml, Document ID: 7f4b9d33-0f4d-4b79-a6f8-8bc12edb9d1d

###############################################################################
# Copyright (c) 2026 Obeo.
# This program and the accompanying materials
# are made available under the terms of the Eclipse Public License v2.0
# which accompanies this distribution, and is available at
# https://www.eclipse.org/legal/epl-2.0/
#
# SPDX-License-Identifier: EPL-2.0
#
# Contributors:
#     Obeo - initial API and implementation
###############################################################################

import argparse
from pathlib import Path

import requests  (1)


GRAPHQL_ENDPOINT = "/api/graphql"
DOWNLOAD_ENDPOINT = "/api/editingcontexts/{editing_context_id}/documents/{document_id}"


fetch_editing_context_query = """
query FetchEditingContext($projectId: ID!) {
  viewer {
    project(projectId: $projectId) {
      currentEditingContext {
        id
      }
    }
  }
}
"""


def get_graphql_url(url):
    return f"{url.rstrip('/')}{GRAPHQL_ENDPOINT}"


def get_download_url(url, editing_context_id, document_id):
    return f"{url.rstrip('/')}{DOWNLOAD_ENDPOINT.format(editing_context_id=editing_context_id, document_id=document_id)}"


def print_graphql_errors(data):
    errors = data.get("errors", [])
    for error in errors:
        print(f"GraphQL error: {error.get('message', error)}")


def fetch_editing_context_id(url, project_id):  (2)
    response = requests.post(
        get_graphql_url(url),
        json={
            "query": fetch_editing_context_query,
            "variables": {"projectId": project_id},
        },
    )

    if response.status_code != 200:
        print(f"Error fetching editing context: {response.status_code} - {response.text}")
        return None

    data = response.json()
    if data.get("errors"):
        print_graphql_errors(data)
        return None

    project = data.get("data", {}).get("viewer", {}).get("project")
    if not project:
        print(f"Project not found: {project_id}")
        return None

    editing_context = project.get("currentEditingContext")
    if not editing_context:
        print(f"Editing context not found for project: {project_id}")
        return None

    return editing_context.get("id")


def download_sysml_file(url, project_id, document_id, output_path):  (3)
    editing_context_id = fetch_editing_context_id(url, project_id)  (6)
    if not editing_context_id:
        return False

    response = requests.get(
        get_download_url(url, editing_context_id, document_id),  (4)
        headers={"Accept": "text/html"},
        stream=True,  (5)
    )

    if response.status_code != 200:
        print(f"Error downloading SysML file: {response.status_code} - {response.text}")
        return False

    output_path.parent.mkdir(parents=True, exist_ok=True)
    with open(output_path, "wb") as file:
        for chunk in response.iter_content(chunk_size=8192):
            if chunk:
                file.write(chunk)

    print(f"SysML file downloaded successfully: {output_path}")
    return True


def parse_arguments():
    parser = argparse.ArgumentParser(description="Download a SysML textual file from a SysON project")
    parser.add_argument(
        "arguments",
        nargs="+",
        help="Either: project-id document-id output-path, or: url project-id document-id output-path",
    )
    args = parser.parse_args()

    if len(args.arguments) == 3:
        args.url = "http://localhost:8080"
        args.project_id = args.arguments[0]
        args.document_id = args.arguments[1]
        args.output_path = Path(args.arguments[2])
    elif len(args.arguments) == 4:
        args.url = args.arguments[0]
        args.project_id = args.arguments[1]
        args.document_id = args.arguments[2]
        args.output_path = Path(args.arguments[3])
    else:
        parser.error("expected either: project-id document-id output-path, or: url project-id document-id output-path")

    return args


if __name__ == "__main__":
    args = parse_arguments()
    output_path = args.output_path.expanduser().resolve()

    if not download_sysml_file(args.url, args.project_id, args.document_id, output_path):  (7)
        exit(1)

$ python download_sysml_file.py project-id document-id output-file.sysml
$ python download_sysml_file.py url-of-syson-server project-id document-id output-file.sysml

$ python download_sysml_file.py 76bb3f29-17d1-465a-a2ca-a331978c36f3 3cb6f3b1-8a10-41b7-9a08-d32b66e28c6f /Users/myUserFolder/myFolder/mySysMLv2File.sysml

SysML file downloaded successfully: /Users/myUserFolder/myFolder/mySysMLv2File.sysml

# These examples are adapted from the SysML v2 API Cookbook, available at
# https://github.com/Systems-Modeling/SysML-v2-API-Cookbook, maintained by the
# Object Management Group (OMG).
# The original cookbook is designed for use with Jupyter Lab.
# These examples have been adapted to run as standalone Python scripts, making
# them suitable for use in various environments, including SysON.
# They showcase practical usage scenarios and may include additional functionality
# or modifications tailored to specific needs.

import requests  (1)
from init_api import parse_arguments
from init_api import init_sysmlv2_api
from fetch_commits import get_last_commit_id


def fetch_element(host, project_id, commit_id, element_id):  (2)
    element_url = f"{host}/projects/{project_id}/commits/{commit_id}/elements/{element_id}"  (3)
    response = requests.get(element_url)  (4)
    if response.status_code == 200:
        return response.json()

    print(f"Unable to fetch element: {response.status_code} - {response.text}")
    return None


def delete_element(host, project_id, element_id):  (5)
    commit_id = get_last_commit_id(host, project_id)
    if not commit_id:
        print("Deletion aborted: unable to determine the latest commit.")
        return False

    element = fetch_element(host, project_id, commit_id, element_id)
    if not element:
        print(f"Deletion aborted: element '{element_id}' was not found.")
        return False

    print(
        f"Deleting element '{element.get('name') or 'N/A'}' "
        f"(id = {element['@id']}, type = {element['@type']})"
    )

    commit_url = f"{host}/projects/{project_id}/commits"  (6)
    commit_body = {
        "@type": "Commit",
        "change": [
            {
                "@type": "DataVersion",
                "identity": {
                    "@id": element_id,
                    "@type": "DataIdentity",
                },
            }
        ],
    }  (7)

    response = requests.post(commit_url, json=commit_body)  (8)
    if response.status_code != 201:
        print(f"Error deleting element: {response.status_code} - {response.text}")
        return False

    print("Delete commit created successfully.")

    new_commit_id = get_last_commit_id(host, project_id)  (9)
    if not new_commit_id:
        print("Deletion verification skipped: unable to determine the latest commit.")
        return True

    verification_url = f"{host}/projects/{project_id}/commits/{new_commit_id}/elements/{element_id}"
    verification_response = requests.get(verification_url)  (10)
    if verification_response.status_code == 404:
        print(f"Element '{element_id}' deleted successfully.")
        return True

    print(
        "Deletion verification failed: "
        f"the element is still accessible ({verification_response.status_code})."
    )
    return False


if __name__ == "__main__":
    args = parse_arguments()
    host = init_sysmlv2_api()
    project_id = args.project_id
    element_id = args.element_id

    if not element_id:
        raise SystemExit("Usage: python delete_element.py <project-id> <element-id>")

    delete_element(host, project_id, element_id)

$ python delete_element.py your-project-id your-element-id

Commit ID: 63a03bd8-a81a-4818-801a-01790ce8a086
Last Commit ID: 63a03bd8-a81a-4818-801a-01790ce8a086
Deleting element 'battery' (id = 7d5e52f4-6fd0-4f3b-9daa-9cb7f0c3e501, type = PartUsage)
Delete commit created successfully.
Commit ID: 63a03bd8-a81a-4818-801a-01790ce8a086
Commit ID: 6f70be18-0117-4e2d-b947-a6bbf2981b63
Last Commit ID: 6f70be18-0117-4e2d-b947-a6bbf2981b63
Element '7d5e52f4-6fd0-4f3b-9daa-9cb7f0c3e501' deleted successfully.