podman-mvp/contracts/API_GOLDEN.md

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/volumes

Curl: curl -s http://127.0.0.1:8081/api/volumes

Response type: Array of Podman volume objects (raw Podman passthrough).

Golden keys per item:

• Name
• Driver
• Mountpoint
• CreatedAt
• Labels

Golden example: [ { "Name": "my-volume", "Driver": "local", "Mountpoint": "/home/kodi/.local/share/containers/storage/volumes/my-volume/_data", "CreatedAt": "2026-03-01T12:00:00Z", "Labels": {} } ]

================================================== POST /api/volumes

Request body (JSON):

• name (string, required)
• driver (string, optional, default "local")
• labels (object, optional)
• driverOpts (object, optional)

Response: created volume object (raw Podman passthrough).

================================================== DELETE /api/volumes/{name}

Response on success (204 from Podman): {"ok": true}

Error responses forwarded from Podman (e.g. 409 if in use).

================================================== POST /api/volumes/prune

Response: array of pruned volume names (raw Podman passthrough).

================================================== GET /api/volumes/{name}/exists

Response: {"exists": true} — volume bestaat (Podman 204) {"exists": false} — volume niet gevonden (Podman 404)

================================================== 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.