feat(api): Codex: add /health endpoint with podman + systemd checks

2026-02-25 13:16:53 +01:00
parent ebb6d755a0
commit b89a31a068
7 changed files with 536 additions and 0 deletions
@@ -0,0 +1,181 @@
+# API_GOLDEN.md — podman-mvp
+
+Purpose:
+Freeze existing API response contracts used by the WebUI.
+Existing response structures MUST remain backward compatible.
+
+Rules:
+- Existing JSON keys MUST NOT be removed.
+- Existing JSON keys MUST NOT be renamed.
+- Data types of listed keys MUST NOT change.
+- New optional fields are allowed.
+- New endpoints are allowed.
+- Podman passthrough responses must remain raw Podman responses.
+
+API accessed via proxy:
+http://127.0.0.1:8081/api
+
+
+==================================================
+GET /api/containers-dashboard
+==================================================
+
+Curl:
+curl -s http://127.0.0.1:8081/api/containers-dashboard
+
+Response type:
+Array of container objects.
+
+Golden keys per item:
+- Names
+- Image
+- State
+- Status
+- Ports
+- PodName
+- _dashboard_source
+- _dashboard_published_ports
+- _dashboard_unit
+- _dashboard_def_path
+
+Golden example:
+[
+  {
+    "Names": ["mvp-webui"],
+    "Image": "docker.io/library/httpd:2.4",
+    "State": "running",
+    "Status": "",
+    "Ports": [],
+    "PodName": "mvp-pod",
+    "_dashboard_source": "podman",
+    "_dashboard_published_ports": [
+      "8080:8000/tcp",
+      "8081:8081/tcp"
+    ],
+    "_dashboard_unit": null,
+    "_dashboard_def_path": null
+  }
+]
+
+
+==================================================
+GET /api/pods-dashboard
+==================================================
+
+Curl:
+curl -s http://127.0.0.1:8081/api/pods-dashboard
+
+Response type:
+Array of pod dashboard objects.
+
+Golden keys per item:
+- Name
+- Status
+- Containers
+- Unit
+- Source
+
+Golden example:
+[
+  {
+    "Name": "mvp-pod",
+    "Status": "Running",
+    "Containers": [
+      "mvp-backend",
+      "mvp-webui"
+    ],
+    "Unit": "pod-mvp-pod.service",
+    "Source": "podman"
+  }
+]
+
+
+==================================================
+GET /api/images
+==================================================
+
+Curl:
+curl -s http://127.0.0.1:8081/api/images
+
+Response type:
+Array of Podman image objects.
+
+Golden keys per item:
+- RepoTags
+- RepoDigests
+- Created
+- Size
+- Containers
+- Digest
+- Arch
+- Os
+
+Golden example:
+[
+  {
+    "RepoTags": [
+      "docker.io/library/httpd:2.4"
+    ],
+    "RepoDigests": [
+      "docker.io/library/httpd@sha256:..."
+    ],
+    "Created": 1770085385,
+    "Size": 120210217,
+    "Containers": 1,
+    "Digest": "sha256:...",
+    "Arch": "amd64",
+    "Os": "linux"
+  }
+]
+
+
+==================================================
+GET /api/networks/meta
+==================================================
+
+Curl:
+curl -s http://127.0.0.1:8081/api/networks/meta
+
+Golden keys:
+- networkBackend
+- rootless
+- infoEndpoint
+
+Golden example:
+{
+  "networkBackend": "netavark",
+  "rootless": true,
+  "infoEndpoint": "http+unix://%2Frun%2Fuser%2F1000%2Fpodman%2Fpodman.sock/v5.4.2/libpod/info"
+}
+
+
+==================================================
+GET /api/openapi.json
+==================================================
+
+Curl:
+curl -s http://127.0.0.1:8081/api/openapi.json
+
+Contract:
+OpenAPI schema must remain available for tooling and inspection.
+
+Required top-level keys:
+- openapi
+- info
+- paths
+
+
+==================================================
+GENERAL BACKWARD COMPATIBILITY RULE
+==================================================
+
+The following dashboard endpoints are considered UI-critical:
+
+- /containers-dashboard
+- /pods-dashboard
+- /images
+- /networks/meta
+
+Changes affecting these endpoints must be proposed before implementation.
+
+System stability has priority over structural refactoring.