ProxmoxVED/docs/misc/api.func/README.md

api.func Documentation

Overview

The api.func file provides Proxmox API integration and diagnostic reporting functionality for the Community Scripts project. It handles API communication, error reporting, and status updates to the community-scripts.org API.

Purpose and Use Cases

• API Communication: Send installation and status data to community-scripts.org API
• Diagnostic Reporting: Report installation progress and errors for analytics
• Error Description: Provide detailed error code explanations
• Status Updates: Track installation success/failure status
• Analytics: Contribute anonymous usage data for project improvement

Quick Reference

Key Function Groups

• Error Handling: get_error_description() - Convert exit codes to human-readable messages
• API Communication: post_to_api(), post_to_api_vm() - Send installation data
• Status Updates: post_update_to_api() - Report installation completion status

Dependencies

• External: curl command for HTTP requests
• Internal: Uses environment variables from other scripts

Integration Points

• Used by: All installation scripts for diagnostic reporting
• Uses: Environment variables from build.func and other scripts
• Provides: API communication and error reporting services

Documentation Files

📊 API_FLOWCHART.md

Visual execution flows showing API communication processes and error handling.

📚 API_FUNCTIONS_REFERENCE.md

Complete alphabetical reference of all functions with parameters, dependencies, and usage details.

💡 API_USAGE_EXAMPLES.md

Practical examples showing how to use API functions and common patterns.

🔗 API_INTEGRATION.md

How api.func integrates with other components and provides API services.

Key Features

Error Code Descriptions

• Comprehensive Coverage: 50+ error codes with detailed explanations
• LXC-Specific Errors: Container creation and management errors
• System Errors: General system and network errors
• Signal Errors: Process termination and signal errors

API Communication

• LXC Reporting: Send LXC container installation data
• VM Reporting: Send VM installation data
• Status Updates: Report installation success/failure
• Diagnostic Data: Anonymous usage analytics

Diagnostic Integration

• Optional Reporting: Only sends data when diagnostics enabled
• Privacy Respect: Respects user privacy settings
• Error Tracking: Tracks installation errors for improvement
• Usage Analytics: Contributes to project statistics

Common Usage Patterns

Basic API Setup

#!/usr/bin/env bash
# Basic API setup

source api.func

# Set up diagnostic reporting
export DIAGNOSTICS="yes"
export RANDOM_UUID="$(uuidgen)"

# Report installation start
post_to_api

Error Reporting

#!/usr/bin/env bash
source api.func

# Get error description
error_msg=$(get_error_description 127)
echo "Error 127: $error_msg"
# Output: Error 127: Command not found: Incorrect path or missing dependency.

Status Updates

#!/usr/bin/env bash
source api.func

# Report successful installation
post_update_to_api "success" 0

# Report failed installation
post_update_to_api "failed" 127

Environment Variables

Required Variables

• DIAGNOSTICS: Enable/disable diagnostic reporting ("yes"/"no")
• RANDOM_UUID: Unique identifier for tracking

Optional Variables

• CT_TYPE: Container type (1 for LXC, 2 for VM)
• DISK_SIZE: Disk size in GB
• CORE_COUNT: Number of CPU cores
• RAM_SIZE: RAM size in MB
• var_os: Operating system type
• var_version: OS version
• DISABLEIP6: IPv6 disable setting
• NSAPP: Namespace application name
• METHOD: Installation method

Internal Variables

• POST_UPDATE_DONE: Prevents duplicate status updates
• API_URL: Community scripts API endpoint
• JSON_PAYLOAD: API request payload
• RESPONSE: API response

Error Code Categories

General System Errors

• 0-9: Basic system errors
• 18, 22, 28, 35: Network and I/O errors
• 56, 60: TLS/SSL errors
• 125-128: Command execution errors
• 129-143: Signal errors
• 152: Resource limit errors
• 255: Unknown critical errors

LXC-Specific Errors

• 100-101: LXC installation errors
• 200-209: LXC creation and management errors

Docker Errors

• 125: Docker container start errors

Best Practices

Diagnostic Reporting

1. Always check if diagnostics are enabled
2. Respect user privacy settings
3. Use unique identifiers for tracking
4. Report both success and failure cases

Error Handling

1. Use appropriate error codes
2. Provide meaningful error descriptions
3. Handle API communication failures gracefully
4. Don't block installation on API failures

API Usage

1. Check for curl availability
2. Handle network failures gracefully
3. Use appropriate HTTP methods
4. Include all required data

Troubleshooting

Common Issues

1. API Communication Fails: Check network connectivity and curl availability
2. Diagnostics Not Working: Verify DIAGNOSTICS setting and RANDOM_UUID
3. Missing Error Descriptions: Check error code coverage
4. Duplicate Updates: POST_UPDATE_DONE prevents duplicates

Debug Mode

Enable diagnostic reporting for debugging:

export DIAGNOSTICS="yes"
export RANDOM_UUID="$(uuidgen)"

API Testing

Test API communication:

source api.func
export DIAGNOSTICS="yes"
export RANDOM_UUID="test-$(date +%s)"
post_to_api

Related Documentation

• core.func - Core utilities and error handling
• error_handler.func - Error handling utilities
• build.func - Container creation with API integration
• tools.func - Extended utilities with API integration

---

This documentation covers the api.func file which provides API communication and diagnostic reporting for all Proxmox Community Scripts.