[doc] Add new python recipe to delete an element

Signed-off-by: Axel RICHARD <axel.richard@obeo.fr>

Author: AxelRICHARD

doc/content/modules/developer-guide/examples/delete_element.py

@@ -0,0 +1,90 @@
+# 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)

doc/content/modules/developer-guide/pages/api/api-cookbook.adoc

@@ -67,3 +67,5 @@ include::developer-guide:partial$create_element_recipe.adoc[leveloffset=+2]
 include::developer-guide:partial$new_objects_from_text.adoc[leveloffset=+2]
 
 include::developer-guide:partial$import_sysml_file_recipe.adoc[leveloffset=+2]
+
+include::developer-guide:partial$delete_element_recipe.adoc[leveloffset=+2]

doc/content/modules/developer-guide/partials/delete_element_recipe.adoc

@@ -0,0 +1,79 @@
+= Delete element recipe (python script)
+
+Learn how to delete an element programmatically.
+Each recipe includes a detailed explanation, step-by-step instructions, and sample code.
+
+Recipes covered:
+
+* <<delete_an_element>>: Delete an element from a project by creating a commit.
+
+[#delete_an_element]
+== Delete an element
+This example demonstrates how to delete an existing element by using the {product} REST API.
+The script first fetches the latest commit of the target project, retrieves the element to confirm it exists, and then creates a new commit containing a deletion change for that element.
+After the commit is created, the script verifies that the element is no longer accessible in the latest commit.
+
+[NOTE]
+====
+To delete an element through the commit API, send a `DataVersion` with its `identity` set to the target element ID and omit the `payload`.
+When an element is deleted, {product} also removes incoming relationships to maintain model integrity.
+====
+
+Example script to delete an element:
+
+[source,python]
+.delete_element.py
+----
+include::example$delete_element.py[]
+----
+
+*What this code does*:
+
+<1> *Import required libraries*:
+
+* `requests`: Used for sending HTTP requests.
+<2> *Define the `fetch_element` function* with four parameters:
+
+* `host`: The base API address.
+* `project_id`: The UUID of the project.
+* `commit_id`: The UUID of the commit in which the element is read.
+* `element_id`: The UUID of the element to fetch.
+
+<3> Constructs the *API endpoint* URL for retrieving a single element.
+
+<4> *Sends a `GET` request* to confirm the element exists before trying to delete it.
+
+<5> *Define the `delete_element` function* with three parameters:
+
+* `host`: The base API address.
+* `project_id`: The UUID of the project.
+* `element_id`: The UUID of the element to delete.
+
+<6> Constructs the *API endpoint* URL for creating a commit.
+
+<7> Builds the *commit payload* for deletion by setting `identity` and omitting `payload`.
+
+<8> *Sends a `POST` request* to create the delete commit.
+
+<9> Fetches the latest commit again after the delete operation.
+
+<10> *Verifies the deletion* by checking that the element endpoint returns `404`.
+
+Run the script:
+[source,bash]
+----
+$ python delete_element.py your-project-id your-element-id
+----
+
+Output example:
+[source,bash]
+----
+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.
+----