From 1a57de5cb14d727c70c1872cd16a5c3004604ba0 Mon Sep 17 00:00:00 2001 From: Sergey Antropoff Date: Sun, 12 Jul 2026 23:13:18 +0300 Subject: [PATCH] docs: research Proxmox API Viewer source --- docs/api-viewer-research.md | 59 +++++++++++++++++++ .../api-viewer/pve-9.2.3-version.json | 48 +++++++++++++++ .../pve-9.2.3-version.provenance.json | 12 ++++ tests/unit/test_api_viewer_fixture.py | 21 +++++++ 4 files changed, 140 insertions(+) create mode 100644 docs/api-viewer-research.md create mode 100644 tests/fixtures/api-viewer/pve-9.2.3-version.json create mode 100644 tests/fixtures/api-viewer/pve-9.2.3-version.provenance.json create mode 100644 tests/unit/test_api_viewer_fixture.py diff --git a/docs/api-viewer-research.md b/docs/api-viewer-research.md new file mode 100644 index 0000000..af1f179 --- /dev/null +++ b/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. diff --git a/tests/fixtures/api-viewer/pve-9.2.3-version.json b/tests/fixtures/api-viewer/pve-9.2.3-version.json new file mode 100644 index 0000000..0a40cc4 --- /dev/null +++ b/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" +} diff --git a/tests/fixtures/api-viewer/pve-9.2.3-version.provenance.json b/tests/fixtures/api-viewer/pve-9.2.3-version.provenance.json new file mode 100644 index 0000000..93ae134 --- /dev/null +++ b/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/" +} diff --git a/tests/unit/test_api_viewer_fixture.py b/tests/unit/test_api_viewer_fixture.py new file mode 100644 index 0000000..de696bd --- /dev/null +++ b/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"]