Skip to content
GitLab
Commit e9f78402 authored by Micha Mueller's avatar Micha Mueller
Browse files

Update RestAPI documentation

parent 762b2879
Hide whitespace changes
Inline Side-by-side
dcdbpusher/README.md
View file @ e9f78402
......@@ -4,9 +4,7 @@
1. [Global Configuration](#globalConfiguration)
2. [Rest API](#restApi)
1. [Table of queries](#tableOfQueries)
2. [Ressources for GET request](#ressourcesGET)
3. [Ressources for PUT request](#ressourcesPUT)
4. [Examples](#restExamples)
2. [Examples](#restExamples)
3. [MQTT topic](#mqttTopic)
3. [Plugins](#plugins)
1. [IPMI](#ipmi)
......@@ -103,47 +101,111 @@ Tables with allowed ressources sorted by REST methods can be found below. A quer
<table>
<tr>
<td>One</td>
<td>Two</td>
<td colspan="2">Ressource</td>
<td colspan="2">Description</td>
</tr>
<tr>
<td colspan="2" bgcolor="ddd">Three</td>
<td>Query</td>
<td>Value</td>
<td>Opt.</td>
<td>Description</td>
</tr>
<tr>
<td colspan="2">GET /help</td>
<td colspan="2">Return a cheatshee of possible REST API endpoints.</td>
</tr>
<tr>
<td colspan="4">No queries.</td>
</tr>
<tr>
<td colspan="2">GET /plugins</td>
<td colspan="2">List all loaded dcdbpusher plugins.</td>
</tr>
<tr>
<td>json</td>
<td>"true"</td>
<td> X </td>
<td>Format response as json.</td>
</tr>
<tr>
<td colspan="2">GET /sensors</td>
<td colspan="2">List all sensors of a specific plugin.</td>
</tr>
<tr>
<td>plugin</td>
<td>All plugin names.</td>
<td> </td>
<td>Specify the plugin.</td>
</tr>
<tr>
<td>json</td>
<td>"true"</td>
<td> X </td>
<td>Format response as json.</td>
</tr>
<tr>
<td colspan="2">GET /average</td>
<td colspan="2">Get the average of the last readings of a sensor.</td>
</tr>
<tr>
<td>plugin</td>
<td>All plugin names.</td>
<td> </td>
<td>Specify the plugin.</td>
</tr>
<tr>
<td>sensor</td>
<td>All sensor names of the plugin or the analytics manager.</td>
<td> </td>
<td>Specify the sensor within the plugin.</td>
</tr>
<tr>
<td>interval</td>
<td>Number of seconds.</td>
<td> X </td>
<td>Use only readings more recent than (now - interval) for average calculation. Defaults to zero, i.e. all cached sensor readings are included in average calculation.</td>
</tr>
<tr>
<td colspan="2">PUT /start</td>
<td colspan="2">Start a plugin, i.e. its sensors start polling.</td>
</tr>
<tr>
<td>plugin</td>
<td>All plugin names.</td>
<td> </td>
<td>Specify the plugin.</td>
</tr>
<tr>
<td colspan="2">PUT /stop</td>
<td colspan="2">Stop a plugin, i.e. its sensors stop polling.</td>
</tr>
<tr>
<td>plugin</td>
<td>All plugin names.</td>
<td> </td>
<td>Specify the plugin.</td>
</tr>
<tr>
<td colspan="2">PUT /reload</td>
<td colspan="2">Reload a plugin's configuration (includes fresh creation of a plugin's sensors and a plugin restart).</td>
</tr>
<tr>
<td>plugin</td>
<td>All plugin names.</td>
<td> </td>
<td>Specify the plugin.</td>
</tr>
</table>
| Key | Value | Explanation |
|:--- |:----- |:----------- |
| authkey | Your authentication token | The authentication token is required to verify that you are allowed to make this particular request. The authkey query must be included by every request
| json | Format replies to plugins and sensors requests as JSON instead of plain text
| interval | Time-value in [s] | Only for GET request of sensor readings average. One can (optionally) specify a custom time interval for which the average of sensor readings is calculated. By default, every sensor reading in the cache is used to calculate the average.
### Ressources for GET request <a name="ressourcesGET"></a>
| Ressource | Explanation |
|:--------- |:----------- |
| /help | Responds with a small cheatsheet which presents all currently supported ressources.
| /plugins | (Discovery) Returns a list of all currently loaded plugins.
| /[plugin]/sensors | (Discovery) Returns a list of all sensors which belong to [plugin]. To find out which plugins are available one can request the `/plugins` ressource.
| /[plugin]/[sensor]/avg | Calculates and returns the average of the last sensor readings. Can be combined with the interval query.
### Ressources for PUT request <a name="ressourcesPUT"></a>
| Ressource | Explanation |
|:--------- |:----------- |
| /[plugin]/[action] | One can request to do a action on the specified plugin. Currently supported actions are `start`, `stop` and `reload` which start or stop the polling of the sensors of the plugin respectively triggers a reload of the plugin configuration. If a configuration reload is requested, all sensors of the plugin are stopped first. Then new sensors are created and started according to the configuration.
### Examples <a name="restExamples"></a>
Two examples for HTTPS requests:
Two examples for HTTPS requests (authentication credentials not shown):
```bash
GET https://localhost:8000/sysfs/freq1/avg?authkey=myToken;interval=15
GET https://localhost:8000/average?plugin=sysfs;sensor=freq1;interval=15
```
```bash
PUT https://localhost:8000/bacnet/stop?authkey=myToken
PUT https://localhost:8000/stop?plugin=bacnet
```
## MQTT topic <a name="mqttTopic"></a>
......
dcdbpusher/RestAPI.h
View file @ e9f78402
......@@ -36,48 +36,55 @@ public:
//TODO rewrite help-section + README + endpoint docs once finished
// String used as a response for the REST GET /help command
const string restCheatSheet = "dcdbpusher RESTful API cheatsheet:\n"
" -GET: /help This help message\n"
" /analytics/help\n"
" An help message for data analytics commands\n"
" /plugins List of currently loaded plugins (Discovery)\n"
" /[plugin]/sensors\n"
" List of currently running sensors which belong\n"
" to the specified plugin (Discovery)\n"
" /[plugin]/[sensor]/avg?interval=[timeInSec]\n"
" Average of last sensor readings from the last\n"
" [interval] seconds or of all cached readings\n"
" if no interval is given\n"
" -PUT: /[plugin]/[start|stop|reload]\n"
" Start/stop the sensors of the plugin or\n"
" reload the plugin configuration\n"
" -GET: /help This help message.\n"
" /analytics/help An help message for data analytics commands.\n"
" /plugins?[json] D List of currently loaded plugins.\n"
" /sensors?plugin;[json]\n"
" D List of currently running sensors which belong to\n"
" the specified plugin.\n"
" /average?plugin;sensor;[interval]\n"
" Average of last sensor readings from the last\n"
" [interval] seconds or of all cached readings if no\n"
" interval is given.\n"
" -PUT: /start?plugin Start the sensors of the plugin.\n"
" /stop?plugin Stop the sensors of the plugin.\n"
" /reload?plugin Reload the plugin configuration.\n"
"\n";
// String used as a response for the REST GET /help command
const string anRestCheatSheet = "dcdbpusher analytics RESTful API cheatsheet:\n"
" -GET: /analytics/plugins List of currently loaded plugins (Discovery)\n"
" /analytics/[plugin]/analyzers\n"
" List of running analyzers in the specified\n"
" data analytics plugin\n"
" /analytics/[plugin]/[analyzer]/sensors\n"
" List of currently running sensors which belong\n"
" to the specified data analytics plugin (Discovery)\n"
" /analytics/[plugin]/[analyzer]/units\n"
" List of units to which sensors are associated in the\n"
" specified data analytics plugin (Discovery)\n"
" -PUT: /analytics/[plugin]/[analyzer]/[start|stop|reload]\n"
" Start/stop the analyzers of the plugin or\n"
" reload the plugin configuration\n"
" /analytics/[plugin]/[analyzer]/compute\n"
" Perform computation of the given analyzer\n"
" in real-time. A \"unit\" query, specifying\n"
" the target unit must be included\n"
" /analytics/[plugin]/[analyzer]/[action]\n"
" Perform plugin-specific actions\n"
" (refer to documentation)\n"
"(All commands must be prepended by \"/analytics\" !)\n"
" -GET: /plugins?[json] D List off currently loaded plugins.\n"
" /sensors?plugin;[analyzer];[json]\n"
" D List of currently running sensors which belong to\n"
" the specified plugin (and analyzer).\n"
" /analyzers?plugin;[json]\n"
" D List of running analyzers in the specified data\n"
" analytics plugin.\n"
" /units?plugin;[analyzer];[json]\n"
" D List of units to which sensors are associated in\n"
" the specified data analytics plugin (and analyzer).\n"
" -PUT: /start?[plugin];[analyzer]\n"
" Start all or only a specific analytics plugin or\n"
" start only a specific analyzer within a plugin.\n"
" /stop?[plugin];[analyzer]\n"
" Stop all or only a specific analytics plugin or\n"
" stop only a specific analyzer within a plugin.\n"
" /reload?[plugin] Reload all or only a specific analytics plugin.\n"
" /compute?plugin;analyzer;[unit];[json]\n"
" Query the specified analyzer for a unit. Default\n"
" unit is the root.\n"
" /analyzer?plugin;action;[analyzer]\n"
" Do a custom analyzer action for all or only an\n"
" selected analyzer within a plugin (refer to plugin\n"
" documentation).\n"
"\n"
"D = Discovery method\n"
"All resources have to be prepended by host:port.\n"
"A query can be appended as ?query=[value] at the end. Multiple queries\n"
"need to be separated by semicolons(';')\n";
"need to be separated by semicolons(';'). \"query=value\" syntax was shortened\n"
"to \"query\" for readability. Optional queries are marked with [ ]\n";
private:
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

LRZ Homepage | Datenschutz | Dokumentation und Betriebsbedingungen | Impressum