[doc] Add new recipes in API cookbook

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

Author: AxelRICHARD

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

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

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

@@ -55,13 +55,6 @@
 """
 
 
-def build_headers(token):  # <2>
-    headers = {}
-    if token:
-        headers["Authorization"] = f"Bearer {token}"
-    return headers
-
-
 def get_graphql_url(url):
     return f"{url.rstrip('/')}{GRAPHQL_ENDPOINT}"
 
@@ -76,14 +69,13 @@ def print_graphql_errors(data):
         print(f"GraphQL error: {error.get('message', error)}")
 
 
-def fetch_editing_context_id(url, project_id, token):  # <3>
+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},
         },
-        headers=build_headers(token),
     )
 
     if response.status_code != 200:
@@ -113,7 +105,7 @@ def print_messages(messages):
         print(f"{message.get('level', 'INFO')}: {message.get('body', '')}")
 
 
-def import_sysml_file(url, file_path, editing_context_id, read_only, token):  # <4>
+def import_sysml_file(url, file_path, editing_context_id, read_only):  # <3>
     operation_id = str(uuid.uuid4())
     operations = {
         "query": upload_document_mutation,
@@ -131,7 +123,7 @@ def import_sysml_file(url, file_path, editing_context_id, read_only, token):  #
     }
 
     with open(file_path, "rb") as file:
-        response = requests.post(  # <5>
+        response = requests.post(  # <4>
             get_graphql_upload_url(url),
             data={
                 "operations": json.dumps(operations),
@@ -140,7 +132,6 @@ def import_sysml_file(url, file_path, editing_context_id, read_only, token):  #
             files={
                 "0": (file_path.name, file, "text/plain"),
             },
-            headers=build_headers(token),
         )
 
     if response.status_code not in (200, 201):
@@ -176,11 +167,6 @@ def parse_arguments():
         nargs="+",
         help="Either: file-path project-id, or: url file-path project-id",
     )
-    parser.add_argument(
-        "--token",
-        type=str,
-        help="Bearer token used to authenticate on the SysON server",
-    )
     parser.add_argument(
         "--read-only",
         action="store_true",
@@ -210,9 +196,9 @@ def parse_arguments():
         print(f"File not found: {file_path}")
         exit(1)
 
-    editing_context_id = fetch_editing_context_id(args.url, args.project_id, args.token)  # <6>
+    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, args.token):  # <7>
+    if not import_sysml_file(args.url, file_path, editing_context_id, args.read_only):  # <6>
         exit(1)

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

@@ -0,0 +1,97 @@
+###############################################################################
+# 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}")

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

@@ -68,4 +68,8 @@ 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$retrieve_project_documents_recipe.adoc[leveloffset=+2]
+
+include::developer-guide:partial$download_sysml_file_recipe.adoc[leveloffset=+2]
+
 include::developer-guide:partial$delete_element_recipe.adoc[leveloffset=+2]