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