Podman API

More design thoughts and justifications to be added later, these are just the protocol specs.

This design is not meant to be followed, it's just my first sketch at listing everything we might need.

[TODO: Add the curl scripts I used for testing]

Configuration

Config

Configuration class that loads settings from environment variables. - MAX_WORKERS: Thread pool size (default: 10) - DEBUG: Enable debug mode (default: False) - REQUEST_TIMEOUT: Operation timeout in seconds (default: 30)

Custom Exceptions

PodmanAPIError(message, status_code=500) Custom exception for API errors with HTTP status codes.

Decorators

@handle_errors Decorator that catches exceptions and converts them to PodmanAPIError: - Catches asyncio.TimeoutError → 408 Timeout - Catches “not found” errors → 404 Not Found - Catches other exceptions → 500 Internal Server Error

@validate_json(required_fields=None) Decorator that validates JSON request data: - Ensures request contains valid JSON - Checks for required fields - Returns 400 Bad Request if validation fails

Core API Class

• • PodmanAPI.__init__()** Initializes the API with a thread pool executor.

PodmanAPI._get_client() Returns a new Podman client instance.

PodmanAPI._run_async(func, timeout=30) Executes a function asynchronously in the thread pool with timeout.

PodmanAPI._handle_exec_result(result) Helper that normalizes exec_run results to (exit_code, output_string).

Container Management

create_container(config) Creates and starts a new container. - Input: {image, name, command?, environment?, ports?, volumes?, user?} - Returns: {id, name, status}

start_container(name) Starts an existing container. - Input: Container name - Returns: {name, status}

stop_container(name) Stops a running container. - Input: Container name - Returns: {name, status}

remove_container(name, force=False) Removes a container. - Input: Container name, force flag - Returns: {name, removed}

list_containers() Lists all containers (running and stopped). - Returns: Array of {id, name, status, image}

get_container_logs(name, tail=100) Retrieves container logs. - Input: Container name, number of lines - Returns: {logs}

Host Operations

add_user(container_name, user_config) Creates a user inside a container. - Input: Container name, {username, password?, shell?} - Returns: {username, created}

add_file(container_name, file_config) Creates a file inside a container. - Input: Container name, {dest_path, content} - Returns: {dest_path, size}

execute_command(container_name, command, user=None) Executes a command inside a container. - Input: Container name, command string, optional user - Returns: {exit_code, output, success}

shutdown() Gracefully shuts down the thread pool executor.

Error Handlers

handle_podman_error(error) Flask error handler for PodmanAPIError exceptions. - Returns structured JSON error response with timestamp

handle_internal_error(error) Flask error handler for 500 Internal Server Error. - Logs error and returns generic error response

API Routes

POST /api/v1/containers Creates a new container. Requires image and name fields.

POST /api/v1/containers/<name>/start Starts the specified container.

POST /api/v1/containers/<name>/stop Stops the specified container.

DELETE /api/v1/containers/<name>?force=bool Removes the specified container. Optional force parameter.

GET /api/v1/containers Lists all containers.

GET /api/v1/containers/<name>/logs?tail=int Gets container logs. Optional tail parameter (default: 100).

POST /api/v1/containers/<name>/users Adds a user to the container. Requires username field.

POST /api/v1/containers/<name>/files Adds a file to the container. Requires dest_path and content fields.

POST /api/v1/containers/<name>/exec Executes a command in the container. Requires command field.

GET /api/v1/health Health check endpoint. Returns Podman connection status.

GET /api/v1/metrics Returns API metrics including uptime and thread pool status.

Signal Handlers

shutdown_handler(sig, frame) Handles SIGINT and SIGTERM signals for graceful shutdown. - Logs signal details including source file and line number - Shuts down thread pool and exits cleanly

Response Format

Successful requests will look like this:

{
  "success": true,
  "container|user|file|execution": { ... },
  "timestamp": "ISO-8601-timestamp"
}

Errors will look like this:

{
  "success": false,
  "error": {
    "message": "Error description",
    "code": 400,
    "type": "ErrorType"
  },
  "timestamp": "ISO-8601-timestamp"
}