kodi
182 lines
3.4 KiB
Markdown
182 lines
3.4 KiB
Markdown
# 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.
|