Podman API
## 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"
}
```
