docs: research Proxmox API Viewer source

docs/api-viewer-research.md

@@ -0,0 +1,59 @@
+# Proxmox VE API Viewer research
+
+Research was performed on 2026-07-12 against the official documentation hosted
+by Proxmox Server Solutions GmbH.
+
+## Discovered source
+
+The HTML application at
+[`https://pve.proxmox.com/pve-docs/api-viewer/`](https://pve.proxmox.com/pve-docs/api-viewer/)
+loads ExtJS and one application resource, `apidoc.js`. The machine-readable API
+tree is not fetched from a separate JSON endpoint: it is embedded at the start
+of [`apidoc.js`](https://pve.proxmox.com/pve-docs/api-viewer/apidoc.js) as a
+JavaScript declaration named `apiSchema`. The remainder of that file renders the
+tree and method documentation.
+
+At retrieval, the artifact was 4,277,440 bytes with SHA-256
+`f2b77b57c71f3781a0993cc5062940ef31e0843fd9a6bcfdb4de4dd2001d6d9e`.
+The server reported `Last-Modified: Fri, 03 Jul 2026 09:08:20 GMT` and ETag
+`"4144c0-655b144140900"`.
+
+The adjacent official documentation index identifies the generated
+documentation as Proxmox VE `9.2.3`, dated `Fri Jul 3 11:08:20 CEST 2026`. Its
+timestamp matches the artifact's HTTP last-modified time after timezone
+conversion. This is strong evidence that the current unversioned viewer belongs
+to that documentation build, but the artifact does not contain a dedicated
+top-level snapshot-version field. Importers must therefore record the index
+version and HTTP metadata as provenance rather than infer a version from an API
+method schema.
+
+## Format and limitations
+
+`apiSchema` is a nested tree of path nodes. Nodes may contain `children`, an
+`info` mapping keyed by HTTP method, `path`, `text`, and `leaf`. Method objects
+contain parameter and return schemas, permissions, descriptions, and flags.
+The schema resembles JSON Schema but is a Proxmox-specific dialect and includes
+fields such as `typetext`, `format_description`, `instance-types`, and numeric
+booleans. Unknown fields must be retained.
+
+The artifact is executable JavaScript, not JSON. A parser must extract only the
+declaration value without evaluating the downloaded program. The URL is
+unversioned and changes in place. Formatting, declaration syntax, variable name,
+tree shape, or bundling may change without notice. Documentation describes the
+declared contract; it does not prove runtime behavior or exact error text for a
+particular installed cluster.
+
+## Offline fallback and sample
+
+The repository stores an extracted, otherwise semantically unmodified `/version`
+node at
+[`tests/fixtures/api-viewer/pve-9.2.3-version.json`](../tests/fixtures/api-viewer/pve-9.2.3-version.json).
+It is deliberately small enough for deterministic parser tests and retains all
+fields from that source node. Its checksum is recorded in the companion
+provenance file. Network retrieval is research/import functionality only; the
+default test suite must use this checked-in fixture.
+
+The fixture is not a complete snapshot and must never be used to claim broad
+Proxmox compatibility. Full imports should preserve the immutable raw
+`apidoc.js`, response metadata, retrieval timestamp, and checksum outside the
+small test-fixture path.

tests/fixtures/api-viewer/pve-9.2.3-version.json

@@ -0,0 +1,48 @@
+{
+  "info": {
+    "GET": {
+      "allowtoken": 1,
+      "description": "API version details, including some parts of the global datacenter config.",
+      "method": "GET",
+      "name": "version",
+      "parameters": {
+        "additionalProperties": 0
+      },
+      "permissions": {
+        "user": "all"
+      },
+      "returns": {
+        "properties": {
+          "console": {
+            "description": "The default console viewer to use.",
+            "enum": [
+              "applet",
+              "vv",
+              "html5",
+              "xtermjs"
+            ],
+            "optional": 1,
+            "type": "string"
+          },
+          "release": {
+            "description": "The current Proxmox VE point release in `x.y` format.",
+            "type": "string"
+          },
+          "repoid": {
+            "description": "The short git revision from which this version was build.",
+            "pattern": "[0-9a-fA-F]{8,64}",
+            "type": "string"
+          },
+          "version": {
+            "description": "The full pve-manager package version of this node.",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      }
+    }
+  },
+  "leaf": 1,
+  "path": "/version",
+  "text": "version"
+}

tests/fixtures/api-viewer/pve-9.2.3-version.provenance.json

@@ -0,0 +1,12 @@
+{
+  "artifact_etag": "\"4144c0-655b144140900\"",
+  "artifact_last_modified": "Fri, 03 Jul 2026 09:08:20 GMT",
+  "artifact_sha256": "f2b77b57c71f3781a0993cc5062940ef31e0843fd9a6bcfdb4de4dd2001d6d9e",
+  "artifact_size": 4277440,
+  "artifact_url": "https://pve.proxmox.com/pve-docs/api-viewer/apidoc.js",
+  "documentation_version": "9.2.3",
+  "fixture_json_pointer": "/5",
+  "fixture_sha256": "ad572969bbab259a10380ec11ac1c67f865e601be7c5aeec201fca368341c3fe",
+  "retrieved_at": "2026-07-12T23:08:59+03:00",
+  "viewer_url": "https://pve.proxmox.com/pve-docs/api-viewer/"
+}

tests/unit/test_api_viewer_fixture.py

@@ -0,0 +1,21 @@
+"""Offline checks for the researched API Viewer sample."""
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any, cast
+
+FIXTURES = Path(__file__).parents[1] / "fixtures" / "api-viewer"
+
+
+def test_version_fixture_matches_provenance() -> None:
+    fixture_path = FIXTURES / "pve-9.2.3-version.json"
+    provenance_path = FIXTURES / "pve-9.2.3-version.provenance.json"
+
+    fixture_bytes = fixture_path.read_bytes()
+    fixture = cast(dict[str, Any], json.loads(fixture_bytes))
+    provenance = cast(dict[str, Any], json.loads(provenance_path.read_bytes()))
+
+    assert fixture["path"] == "/version"
+    assert fixture["info"]["GET"]["method"] == "GET"
+    assert hashlib.sha256(fixture_bytes).hexdigest() == provenance["fixture_sha256"]