Prove the instance before reading or changing it
Start with GET /asterisk/ping and retain its asterisk_id, pong value, server timestamp, request target and collection time. A successful ping proves that one ARI HTTP endpoint answered; it does not prove that the request reached the intended cluster member, that every module is healthy or that call handling is ready.
Use GET /asterisk/info to identify the running system. Its optional only filter accepts build, system, config and status, including comma-separated values. Preserve system version and entity ID, build details, effective configuration locations, startup time and last reload time as separate evidence. Compare those fields with the planned node and maintenance window before any mutation.
Inventory the running module object exactly
GET /asterisk/modules lists running modules and GET /asterisk/modules/{moduleName} reads one case-sensitive name. The Module model exposes name, description, use count, running status and support level. Treat those as a current runtime snapshot, not proof that a binary exists on disk, that its configuration loaded as intended or that every function it supplies passes an application test.
Record the exact module name returned by Asterisk instead of inventing a filename variant. A 404 on the specific read means the module was not found among running modules; a 409 means its information could not be retrieved. Neither response alone proves whether the binary was never installed, was excluded by modules.conf, failed a dependency or failed during initialization.
Reconcile runtime state with loader policy
Asterisk's module loader reads modules.conf. Its controls include autoload, preload, require, preload-require, noload and load; a module marked require that fails to load causes Asterisk to exit with status 2. Compare the running inventory with the effective loader policy, installed module directory and build or package manifest on the same host.
Runtime success and next-start success are different claims. An ad hoc load can make a module available now without making it persistent, while a noload or missing explicit load rule can make it disappear after restart. Conversely, a file and a loader rule do not establish that dependencies and configuration let the module initialize.
Gate load, reload and unload separately
ARI maps POST /asterisk/modules/{moduleName} to load, PUT to reload and DELETE to unload. Each is a different change with different prerequisites and rollback. A documented 409 means the requested action could not complete; unload and reload can also return 404 when the module is not running. Do not turn one failure into an automatic sequence of alternate actions.
Before load, prove package and dependency state plus the intended persistent policy. Before reload, confirm that the named module supports reloading and that its current configuration has passed validation. Before unload, identify dependants, active use and service effect. The CLI documentation warns that forced unload options can crash Asterisk; ARI should not be wrapped in an automation that tries to reproduce or escalate to forced unload behavior.
Separate API completion from service readiness
After an accepted action, repeat the specific module read, compare the full inventory, and collect bounded logs for the same timestamp. Re-check Asterisk status and last reload time only for the kind of change performed. Then test the narrow function supplied by the module: for example, its endpoint technology, application, codec, resource or interface.
A successful HTTP response is not a dependency audit, configuration validation, call test or persistence guarantee. A nonzero use count is not a safe-unload calculator, and a zero value is not proof that unloading has no consequences. Keep runtime telemetry, loader policy and functional acceptance as independent gates.
Make module control an exceptional privilege
Keep ARI on a protected management path, use TLS where supported, issue a dedicated identity, and place module-changing operations behind application authorization, an exact allowlist, change records and concurrency control. Separate read-only inventory from mutation where the surrounding service permits it. Never accept an arbitrary module name or action from an untrusted client.
Acceptance covers intended-node identity, exact module read, missing-module behavior, one approved action in a maintenance window, bounded logs, specific function verification, persistence after the planned lifecycle event and rollback. Restore temporary diagnostics and record the running version. No host, module action, restart or call was tested for this guide.
Sources & applicability
Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.
- Asterisk 23 ARI Asterisk REST API ↗
- Asterisk 23 ARI REST data models ↗
- Asterisk module-loader configuration and CLI controls ↗
- Asterisk configuration for ARI ↗
Examples require adaptation to your topology. No live PBX or hardware testing is claimed.