community-scripts/ProxmoxVED
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ProxmoxVED/docs/api/README.md
CanbiZ 3998b80194 Add comprehensive documentation for all project sections 
Introduced new and updated documentation files across the docs/ directory, including project structure guides, function library references, and standardized READMEs for ct, install, vm, tools, api, and misc. This update fully documents all nine function libraries, provides quick start and learning paths, and mirrors the project structure for easier navigation and contribution.
2025-12-01 11:40:38 +01:00

3.7 KiB
Raw Blame History

API Integration Documentation (/api)

This directory contains comprehensive documentation for API integration and the /api directory.

Overview

The /api directory contains the Proxmox Community Scripts API backend for diagnostic reporting, telemetry, and analytics integration.

Key Components

Main API Service

Located in /api/main.go:

  • RESTful API for receiving telemetry data
  • Installation statistics tracking
  • Error reporting and analytics
  • Performance monitoring

Integration with Scripts

The API is integrated into all installation scripts via api.func:

  • Sends installation start/completion events
  • Reports errors and exit codes
  • Collects anonymous usage statistics
  • Enables project analytics

Documentation Structure

API documentation covers:

  • API endpoint specifications
  • Integration methods
  • Data formats and schemas
  • Error handling
  • Privacy and data handling

Key Resources

API Functions

The api.func library provides:

post_to_api()

Send container installation data to API.

Usage:

post_to_api CTID STATUS APP_NAME

post_update_to_api()

Report application update status.

Usage:

post_update_to_api CTID APP_NAME VERSION

get_error_description()

Get human-readable error description from exit code.

Usage:

ERROR_DESC=$(get_error_description EXIT_CODE)

API Integration Points

In Container Creation (ct/AppName.sh)

  • Called by build.func to report container creation
  • Sends initial container setup data
  • Reports success or failure

In Installation Scripts (install/appname-install.sh)

  • Called at start of installation
  • Called on installation completion
  • Called on error conditions

Data Collected

  • Container/VM ID
  • Application name and version
  • Installation duration
  • Success/failure status
  • Error codes (if failure)
  • Anonymous usage metrics

Privacy

All API data:

  • ✅ Anonymous (no personal data)
  • ✅ Aggregated for statistics
  • ✅ Used only for project improvement
  • ✅ No tracking of user identities
  • ✅ Can be disabled if desired

API Architecture

Installation Scripts
    │
    ├─ Call: api.func functions
    │
    └─ POST to: https://api.community-scripts.org
                │
                ├─ Receives data
                ├─ Validates format
                ├─ Stores metrics
                └─ Aggregates statistics
                    │
                    └─ Used for:
                       ├─ Download tracking
                       ├─ Error trending
                       ├─ Feature usage stats
                       └─ Project health monitoring

Common API Tasks

Debugging API Issues

If API calls fail:

  1. Check internet connectivity
  2. Verify API endpoint availability
  3. Review error codes in EXIT_CODES.md
  4. Check API function logs
  5. Report issues on GitHub

API Endpoint

Base URL: https://api.community-scripts.org

Endpoints:

  • POST /install - Report container installation
  • POST /update - Report application update
  • GET /stats - Public statistics

Last Updated: December 2025 Maintainers: community-scripts team