RestAPI.h 11.5 KB
Newer Older
1
2
3
//================================================================================
// Name        : RestAPI.h
// Author      : Micha Mueller
Micha Müller's avatar
Micha Müller committed
4
// Contact     : info@dcdb.it
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// Copyright   : Leibniz Supercomputing Centre
// Description : RESTful API for dcdb-pusher.
//================================================================================

//================================================================================
// This file is part of DCDB (DataCenter DataBase)
// Copyright (C) 2019-2019 Leibniz Supercomputing Centre
//
// This program is free software; you can redistribute it and/or
// modify it under the terms of the GNU General Public License
// as published by the Free Software Foundation; either version 2
// of the License, or (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
//================================================================================
27
28
29
30
31
32
33
34

#ifndef DCDBPUSHER_RESTAPI_H_
#define DCDBPUSHER_RESTAPI_H_

#include "RESTHttpsServer.h"

#include <boost/asio.hpp>

35
#include "../analytics/OperatorManager.h"
36
#include "MQTTPusher.h"
37
#include "PluginManager.h"
38
#include "mqttchecker.h"
39

40
41
42
43
44
/**
 * @brief Class providing a RESTful API to pusher via network (HTTPs only).
 *
 * @ingroup pusher
 */
45
class RestAPI : public RESTHttpsServer {
46
47
48
49
50
      public:
	RestAPI(serverSettings_t         settings,
		PluginManager *          pluginManager,
		MQTTPusher *             mqttPusher,
		OperatorManager *        manager,
51
		boost::asio::io_context  &io);
52

53
	virtual ~RestAPI() {}
54

55
56
	// String used as a response for the REST GET /help command
	const string restCheatSheet = "dcdbpusher RESTful API cheatsheet:\n"
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
				      " -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:  /load?plugin;[path];[config]\n"
				      "                            Load a new plugin. Optionally specify path to the\n"
				      "                            shared library and/or the config file for the "
				      "                            plugin.\n"
				      "        /unload?plugin      Unload a plugin.\n"
				      "        /reload?plugin      Reload the plugin configuration.\n"
				      "        /quit?[code]        The pusher quits with the specified\n"
				      "                            return code.\n"
    				      " -POST: /start?plugin       Start the sensors of the plugin.\n"
				      "        /stop?plugin        Stop the sensors of the plugin.\n"
77
				      "\n";
78

79
80
      private:
	/**
81
82
83
84
85
86
87
88
89
     * GET "/help"
     *
     * @brief Return a cheatsheet of possible REST API endpoints.
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required |  -      |        -             |      -
     * Optional |  -      |        -             |      -
     */
90
	void GET_help(endpointArgs);
91

Michael Ott's avatar
Michael Ott committed
92
93
94
95
96
97
98
99
100
101
102
103
	/**
	 * GET "/version"
	 *
	 * @brief Return version number
	 *
	 * Queries  | key     | possible values      | explanation
	 * -------------------------------------------------------------------------
	 * Required |  -      |        -             |      -
	 * Optional |  -      |        -             |      -
	 */
	void GET_version(endpointArgs);
	
104
	/**
105
106
107
108
109
110
111
112
113
     * GET "/plugins"
     *
     * @brief List all loaded dcdbpusher plugins.
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required |  -      |        -             |      -
     * Optional | json    | true                 | format response as json
     */
114
	void GET_plugins(endpointArgs);
115

116
	/**
117
118
119
120
121
122
123
124
125
     * GET "/sensors"
     *
     * @brief List all sensors of a specific plugin.
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required | plugin  | all plugin names     | specify the plugin
     * Optional | json    | true                 | format response as json
     */
126
	void GET_sensors(endpointArgs);
127

128
	/**
129
130
     * GET "/average"
     *
131
132
     * @brief Get the average of the last readings of a sensor. Also allows
     *        access to analytics sensors.
133
134
135
136
137
138
139
140
141
142
143
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required | plugin  | all plugin names     | specify the plugin
     *          | sensor  | all sensor names of  | specify the sensor within the
     *          |         | the plugin or the    | plugin
     *          |         | analytics manager    |
     * Optional | interval| number of seconds    | use only readings more recent
     *          |         |                      | than (now - interval) for
     *          |         |                      | average calculation
     */
144
	void GET_average(endpointArgs);
145

146
	/******************************************************************************/
147

Alessio Netti's avatar
Alessio Netti committed
148
149
150
151
152
153
154
155
156
157
158
159
	/**
	 * PUT "/quit"
	 *
	 * @brief Quits the pusher with a certain return code.
	 *
	 * Queries  | key     | possible values      | explanation
	 * -------------------------------------------------------------------------
	 * Required |  -      |        -             |      -
	 * Optional | code    | integer value        |      return code to be used
	 */
	void PUT_quit(endpointArgs);

160
	/**
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
     * PUT "/load"
     *
     * @brief Load and initialize a plugin but do not start it yet.
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required | plugin  | name of the new      | specify the plugin
     *          |         | plugin               |
     * Optional | path    | file path            | specify a file path where to
     *          |         |                      | search for the shared lib.
     *          |         |                      | Defaults to (usr/lib etc.)
     *          | config  | file path + name     | specify the config file for
     *          |         |                      | the plugin. Defaults to
     *          |         |                      | ./PLUGINNAME.conf
     */
176
	void PUT_load(endpointArgs);
177

178
	/**
179
180
181
182
183
184
185
186
187
     * PUT "/unload"
     *
     * @brief Unload a plugin.
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required | plugin  | all plugin names     | specify the plugin
     * Optional |  -      |        -             |      -
     */
188
	void PUT_unload(endpointArgs);
189

190
	/**
191
     * POST "/start"
192
     *
Micha Mueller's avatar
Micha Mueller committed
193
     * @brief Start a plugin.
194
195
196
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
Micha Mueller's avatar
Micha Mueller committed
197
     * Required | plugin  | all plugin names     | specify the plugin
198
199
     * Optional |  -      |        -             |      -
     */
200
	void POST_start(endpointArgs);
201

202
	/**
203
     * POST "/stop"
204
     *
Micha Mueller's avatar
Micha Mueller committed
205
     * @brief Stop a plugin.
206
207
208
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
Micha Mueller's avatar
Micha Mueller committed
209
     * Required | plugin  | all plugin names     | specify the plugin
210
211
     * Optional |  -      |        -             |      -
     */
212
	void POST_stop(endpointArgs);
213

214
	/**
215
216
     * PUT "/reload"
     *
Micha Mueller's avatar
Micha Mueller committed
217
     * @brief Reload a plugin's configuration (includes plugin restart).
218
219
220
221
222
223
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required | plugin  | all plugin names     | specify the plugin
     * Optional |  -      |        -             |      -
     */
224
	void PUT_reload(endpointArgs);
225

226
	/**
227
228
229
     * PUT "/analytics/reload"
     *
     * @brief Reload configuration and initialization of all or only a specific
230
     *        operator plugin.
231
232
233
234
235
236
237
     *
     * @detail Overwrites the method from the AnalyticsManager to ensure that
     *         MQTTPusher is stopped before reloading plugins.
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required |  -      |        -             |      -
238
     * Optional | plugin  | all operator plugin  | reload only the specified
239
240
     *          |         | names                | plugin
     */
241
	void PUT_analytics_reload(endpointArgs);
242

243
	/**
244
245
     * PUT "/analytics/load"
     *
246
     * @brief Load and initialize an operator plugin but do not start it yet.
247
248
249
250
251
252
253
254
255
256
257
258
259
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required | plugin  | name of the new      | specify the plugin
     *          |         | plugin               |
     * Optional | path    | file path            | specify a file path where to
     *          |         |                      | search for the shared lib.
     *          |         |                      | Defaults to (usr/lib etc.)
     *          | config  | file path + name     | specify the config file for
     *          |         |                      | the plugin. Defaults to
     *          |         |                      | ./PLUGINNAME.conf
     *          
     */
260
	void PUT_analytics_load(endpointArgs);
261

262
	/**
263
264
     * PUT "/analytics/unload"
     *
265
     * @brief Unload a specific operator plugin.
266
267
268
269
270
     *
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required |  -      |        -             |      -
271
     * Optional | plugin  | all operator plugin  | unload only the specified
272
273
     *          |         | names                | plugin
     */
274
	void PUT_analytics_unload(endpointArgs);
275

276
	/**
277
278
279
280
281
282
283
284
     * PUT "/analytics/navigator"
     *
     * @brief Reloads the sensor navigator.
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required |  -      |        -             |      -
     */
285
	void PUT_analytics_navigator(endpointArgs);
286

287
	/******************************************************************************/
288

289
290
291
	// Utility method to reload the sensor navigator whenever needed
	bool reloadQueryEngine(const bool force = false);
	void unloadQueryEngine();
292

293
294
295
	PluginManager *          _pluginManager;
	MQTTPusher *             _mqttPusher;
	OperatorManager *        _manager;
296
297
298
};

#endif /* DCDBPUSHER_RESTAPI_H_ */