Skip to content

GitLab

Currently job artifacts in CI/CD pipelines on LRZ GitLab never expire. Starting from Wed 26.1.2022 the default expiration time will be 30 days (GitLab default). Currently existing artifacts in already completed jobs will not be affected by the change. The latest artifacts for all jobs in the latest successful pipelines will be kept. More information: https://gitlab.lrz.de/help/user/admin_area/settings/continuous_integration.html#default-artifacts-expiration

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:
......
Markdown is supported
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