Currently, the Asterisk REST Interface (ARI) has the ability to retrieve information from Asterisk, but cannot manipulate it. Modifying Asterisk through ARI would be a handy thing to do, which is what this project intends to achieve. To start off, modules and logging channels will be looked at, with the ability to load, unload, and reload modules, as well as the ability to add, retrieve, and rotate log channels.
ARI will be able to load, unload, and reload modules for Asterisk, as well as retrieve information for modules.
The only thing the ARI user will need to know is the name of the module he/she wishes to act upon.
What should happen:
- GET - Returns information for all loaded modules. The path can be extended (ex. /ari/asterisk/modules/app_stack) to get information on a specific module.
- POST - The load module functionality. If you don't have a module loaded that you need, use this.
- PUT - The reload functionality. Refresh, refresh, refresh.
- DELETE - The unload functionality. Not using a module anymore? Unload it with DELETE!
ARI should also be able to add log channels, retrieve them, and rotate them.
What should happen:
- GET - Returns information for all active log channels. Information on a single log channel can be retrieved the same way as a single module.
- POST - Creates a log channel. Name it whatever you want. Can also set the different levels it will monitor.
- PUT - Rotate a log channel.
- DELETE - Deletes the log channel.
No configuration should be needed other than what is necessary for ARI.
Swagger Model Updates
The asterisk resource will be modified, adding two new sections: modules and logging.
This is subject to change.
|/asterisk/modules/get_modules||tests/rest_api||Verify that Asterisk returns a list of loaded modules.|
|/asterisk/modules/get_module||tests/rest_api||Verify that Asterisk returns information on a module, whether it is loaded or not.|
|/asterisk/modules/get_unknown_module||tests/rest_api||Verify that trying to get information on a non-existent module returns a warning message saying that the module does not exist.|
|/asterisk/modules/load_module||tests/rest_api||Verify that a module is loaded to Asterisk, assuming it was not already loaded.|
|/asterisk/modules/load_already_loaded_module||tests/rest_api||Verify that loading a module that is already loaded results in a warning message saying that the module already exists.|
|/asterisk/modules/load_unknown_module||tests/rest_api||Verify that trying to load a module unknown to Asterisk results in two warning messages saying that the file does not exist, and Asterisk could not load the module.|
|/asterisk/modules/unload_module||tests/rest_api||Verify that a module was unloaded from Asterisk, assuming it was not already unloaded.|
|/asterisk/modules/unload_already_unloaded_module||tests/rest_api||Verify that unloading a module that is already unloaded results in a warning message saying that the unload failed, and that the module could not be found.|
|/asterisk/modules/unload_unknown_module||tests/rest_api||Verify that trying to unload a module unknown to Asterisk results in a warning message saying that the unload failed, and the module could not be found.|
|/asterisk/modules/reload_module||tests/rest_api||Verify that a module was reloaded to Asterisk.|
|/asterisk/modules/reload_unloaded_module||tests/rest_api||Verify that reloading a module that is unloaded from Asterisk results in a warning message saying that the module does not exist.|
|/asterisk/modules/reload_unknown_module||tests/rest_api||Verify that trying to reload a module unknown to Asterisk results in a warning message saying the module does not exist.|
|/asterisk/logging/get_logging||tests/rest_api||Verify that information on all log channels was retrieved.|
|/asterisk/logging/get_logging_channel||tests/rest_api||Verify that information on a single log channel was retrieved.|
|/asterisk/logging/get_unknown_logging_channel||tests/rest_api||Verify that trying to retrieve information on a non-existent log channel results in a warning message saying the log channel does not exist.|
|/asterisk/logging/add_logging||tests/rest_api||Verify that a log channel was added to a channel or bridge.|
|/asterisk/logging/add_already_existing_logging||tests/rest_api||Verify that trying to add a log channel that already exists (has the same name) results in a warning message saying the channel already exists, and the channel could not be added.|
|/asterisk/logging/add_logging_invalid_level||tests/rest_api||Verify that trying to add a log channel with a logging level that is unknown to Asterisk results in a warning message saying a logging level was invalid, and that the channel could not be added.|
|/asterisk/logging/rotate_logging||tests/rest_api||Verify that a log channel was rotated from a channel or bridge.|
|/asterisk/logging/rotate_unknown_logging||tests/rest_api||Verify that trying to rotate a non-existent log channel results in a warning message saying the log channel does not exist, and the channel could not be rotated.|
In order for logging and module functionality to be a full fledged ARI Asterisk resource feature it must be planned out accordingly through testing, updating possible non-ARI changes, and lastly updating the ARI information. These processes will be implemented separately to ease the process of peer review.
Phase 1: Writing Tests
We’re still unsure if this is the best way to go about working on this project, but it seemed like a good start for us to wrap our heads around the functionality of modules and logging information.
The tests will be REST API tests.
Phase 2: Updating the ARI Information
Update the ARI information at hand. This phase will consist of generating new swagger bindings, updating the JSON file for the asterisk resource, and finally implementing the system to contain all of the functionality needed for ARI to retrieve information and manipulate that information efficiently. Leave stubs for future implementation.
Phase 3: Updating Possible Non-ARI Changes
The task may require adding some methods to the main code in asterisk. Once again we aren’t sure on this fact but we have to find a way in which we can retrieve the active channel logs and running modules. So, this step may be necessary in the process of the project.
Phase 4: Implementing ARI Stubs
Go back and implement the stubs in phase 2. This will tie everything together, allowing useful information returns when testing the new functionality.
From the perspective of an ARI user, I would want to see a list of operations I can perform, the syntax for those operations, the possible values I could pass in, and examples of these new features being used so that I could use them as a reference for getting my own applications started.