Both Almond and HowRU have json API:s, but they are working differently.
HowRU have a get only API that is easy to use and that does not require authentication. HowRU also have a proxy functionality, meaning that the results of API calls can be provided from multiple Almond servers.
Almond on the other hand does not have any such proxy functionality, but will only return data from the unit where it is installed.
However, Almond API have a richer feature set enabling you not only to retrieve data but also to execute plugins, enable and disable features in the running process and
change variables such as to which topic Almond should write data (if using Kafka) - without needing to restart the application.
Below you will have a list of the calls you can make to the API:s.
The following API calls are currently available with the HowRU API:
| API call | Description |
| /api/status | Short compilation of server state. |
| /api/summary | Same as above. |
| /api/howru | Same as above. |
| /api/howareyou | Same as above. |
| /howru/api/howareyou | Same as above. |
| /howru/monitoring/howareyou | Same as above. |
| /api/criticals | Compilation of all plugins in critical state. |
| /howru/api/criticals | Same as above. |
| /howru/monitoring/criticals | Compilation of all plugins in critical state. |
| /api/warnings | Compilation of all plugins in warning state. |
| /howru/api/warnings | Same as above. |
| /howru/monitoring/warnings | Compilation of all plugins in warning state. |
| /api/ok | Compilation of all plugins in state ok. |
| /api/oks | Same as above. |
| /howru/api/ok | Same as above. |
| /howru/monitoring/ok | Compilation of all plugins in state ok. |
| /api/changes | Compilation of changes |
| /howru/api/changes | Same as above |
| /howru/monitoring/changes | Compilation of changes |
| /api/showall | All plugin results are shown |
| /api/all | Same as above |
| /api/json | Same as above |
| /howeu/api/showall | Same as above |
| /howru/api/all | Same as above |
| /howru/api/json | Same as above |
| /howru/monitoring/json | All plugin results are shown |
| /api/servers | Results from specifik server in multimode. id or name must be provided. |
| /howru/api/servers | Same as above |
| /api/alias | Show results from alias as provided in the aliases.conf file. |
| /api/search?name=searchstring | Search results from string |
| /api/querysearch?name=searchstring | Same as above |
| /howru/api/search?name=searchstring | Same as above |
| /api/query?id=plugin_id | Search result of a specific plugin id |
| /api/plugin?id=plugin_id | Same as above |
| /howru/api/plugin?id=plugin_id | Same as above |
| /api/plugin?index=plugin_index | Result of specific plugin by index_name |
| /howru/monitoring/plugin?id=plugin_id | Result of a specific plugin by id |
| /howru/monitoring/plugin?name=plugin_name | Result of specific plugin by plugin name |
| /howru/settings/plugins | Show settings of plugins running on the server |
| /howru/settings/scheduler | Show all settings in the almond.conf file |
Note All of the API calls can take the parameter whichjson if you want the API to look only in a particular json-file if you are running in multiserver (proxy)-mode.
In multiserver-mode the parameter server can also be used if you want to look at the result from a particular server of many:
will return status information from all servers running under the api.
will only show status from the particular server testserver.test.domain.com.
Apart from the above API calls HowRU also have a number of calls mainly to be used with integration scripts, which are listed here:
| API call | Description |
| /api/countjobs | Returns the number of plugins handled by HowRu. |
| /howru/api/countjobs | Same as above. |
| /api/countservers | Returns the number of servers HowRU is serving. |
| /howru/api/countservers | Same as above. |
| /api/elderpluginrun | Returns a timestamp of the "oldest" plugin execution. |
| /howru/api/elderpluginrun | Same as above. |
| /api/getmaintenance | Returns a list of all plugins that are disabled. |
| /howru/api/getmaintenance | Same as above. |
| /api/getmaintenancelist | Returns a list of the maintenance status of all plugin items. |
| /howru/api/getmaintenancelist | Same as above. |
| /api/lastpluginrun | Returns a timestamp of when the last plugin was executed. |
| /howru/api/lastpluginrun | Same as above. |
| /api/listjobnames | Returns a list with the names of all plugins handled by this HowRU instance. |
| /howru/api/listjobnames | Same as above. |
| /api/listjobs | Returns the name and id of all plugins handled by this HowRU installation. |
| /howru/api/listjobs | Same as above. |
| /api/listservers | Returns the list of all servers handled by this HowRU instance. |
| /howru/api/listservers | Same as above |
| /api/unixdeploytime | Returns the unix timestamp of when the configuration file was last changed. |
| /howru/api/unixdeplytime | Same as above |
| /api/unixupdatetime | Returns a unix timestamp for when plugin configuration was last changed.. |
| /howru/api/servers | Same as above |
The Almond service has its own API, which should be used with more caution than the more easygoing HowRU API. The Almond API, if enabled, is running on the port specified in the
file almond.conf. As a user the HowRU API should generally be preferred to be used in all cases where it provides the same service as the Almond API.
Almond API will require you to send a valid json object which it can evalutate, as will be explained further later. An API call to Almond could look like this:
With Almond API you have the possibility to change some variables that was written in configuration files, read plugin results, run and toggle processes inside Almond as well
as executing plugins,
including sending arbitary parameters to them. While Almond API provide a great opportunity to make integrations with other systems and optimize the Almond process,
but is more complex to use compared to the API provided by HowRU.
Note! All calls to Almond API that involves executing code or change values within the program require you to use a token ackknowledged by Almond.
You find an almond_token_generator in the directory /opt/almond/utilities that will help you create and install tokens.
All calls to Almond API must have the "action" parameter specified, as well as following parameters depending on what you want to achieve.
A list of valid actions are specified below.
Depending of action a number of other parameters are required, where name is usually always required and then depending on the action further parameters such as flags, value and args must be added. The token parameter must be added for all API calls that trigger changes or runs.
You can however run a read command such as the one below without supplementing a token:
You can also retrieve metrics without a token:
As a final more complex example, this call would trigger a plugin to execute a dry run with the arguments passed by the API call:
You can look at the API section in the Almond Admin page after installing the Almond package, to see what types of calls are possible and try them out from there.
