CARestAPI.h 8.33 KB
Newer Older
1
2
3
//================================================================================
// Name        : CARestAPI.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 collectagent.
//================================================================================

//================================================================================
// 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

#ifndef COLLECTAGENT_CARESTAPI_H_
#define COLLECTAGENT_CARESTAPI_H_

#include "RESTHttpsServer.h"

#include "analyticscontroller.h"
34
#include "mqttchecker.h"
35
#include "configuration.h"
36
#include "simplemqttserver.h"
Alessio Netti's avatar
Alessio Netti committed
37
#include <signal.h>
38

39
40
41
42
43
/**
 * @brief Class providing a RESTful API to collect agent via network (HTTPs only).
 *
 * @ingroup ca
 */
44
45
46
class CARestAPI : public RESTHttpsServer {
public:
    CARestAPI(serverSettings_t settings,
47
	      std::map<std::string, influx_t>& influxMap,
48
              SensorCache* sensorCache,
49
	      SensorDataStore* sensorDataStore,
50
51
              AnalyticsController* analyticsController,
              SimpleMQTTServer* mqttServer);
52
53
54
55
56
57
58
59

    virtual ~CARestAPI() {}

    // String used as a response for the REST GET /help command
    const std::string caRestCheatSheet = "collectAgent RESTful API cheatsheet:\n"
                                         " -GET:  /help     This help message.\n"
                                         "        /analytics/help\n"
                                         "                  An help message for data analytics commands.\n"
60
61
                                         "        /hosts\n"
                                         "                  Prints the list of connected hosts.\n"
62
63
64
65
                                         "        /average?sensor;[interval]\n"
                                         "                  Average of last sensor readings from the last\n"
                                         "                  [interval] seconds or of all cached readings\n"
                                         "                  if no interval is given\n"
Alessio Netti's avatar
Alessio Netti committed
66
67
68
                                         " -PUT:  /quit?[code]\n"
                                         "                  The collectagent quits with the specified\n"
                                         "                  return code.\n"
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
                                         "\n";

private:

    /**
     * GET "/help"
     *
     * @brief Return a cheatsheet of possible REST API endpoints.
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required |  -      |        -             |      -
     * Optional |  -      |        -             |      -
     */
    void GET_help(endpointArgs);

Michael Ott's avatar
Michael Ott committed
85
86
87
88
89
90
91
92
93
94
95
96
    /**
     * GET "/version"
     *
     * @brief Return version number.
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required |  -      |        -             |      -
     * Optional |  -      |        -             |      -
     */
    void GET_version(endpointArgs);
    
97
98
99
100
101
102
103
104
105
106
107
108
    /**
     * GET "/hosts"
     *
     * @brief Returns a CSV list of connected hosts and their "last seen" timestamps.
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required |  -      |        -             |      -
     * Optional |  -      |        -             |      -
     */
    void GET_hosts(endpointArgs);

109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
    /**
     * GET "/average"
     *
     * @brief Get the average of the last readings of a sensor.
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required | sensor  | all sensor names of  | specify the sensor within the
     *          |         | the plugin within the| plugin
     *          |         | sensor cache         |
     * Optional | interval| number of seconds    | use only readings more recent
     *          |         |                      | than (now - interval) for
     *          |         |                      | average calculation
     */
    void GET_average(endpointArgs);

Alessio Netti's avatar
Alessio Netti committed
125
126
127
128
129
130
131
132
133
134
135
136
    /**
     * PUT "/quit"
     *
     * @brief Quits the collectagent with a certain return code.
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required |  -      |        -             |      -
     * Optional | code    | integer value        |      return code to be used
     */
    void PUT_quit(endpointArgs);

137
138
139
140
    void GET_ping(endpointArgs);
    void POST_query(endpointArgs);
    void POST_write(endpointArgs);

141
142
143
144
145
146
    /**
     * PUT "/analytics/reload"
     *
     * @brief Reload configuration and initialization of all or only a specific
     *        analytics plugin.
     *
147
     * @detail Overwrites the method from the OperatorManager to ensure that
148
149
150
151
152
153
154
155
156
157
     *         analyticsctonroller is stopped before reloading plugins.
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required |  -      |        -             |      -
     * Optional | plugin  | all analyzer plugin  | reload only the specified
     *          |         | names                | plugin
     */
    void PUT_analytics_reload(endpointArgs);

158
159
160
    /**
     * PUT "/analytics/load"
     *
161
     * @brief Load and initialize an operator plugin but do not start it yet.
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
     *
     * 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
     *          
     */
    void PUT_analytics_load(endpointArgs);

    /**
     * PUT "/analytics/unload"
     *
180
     * @brief Unload a specific operator plugin.
181
182
183
184
185
186
187
188
189
190
     *
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required |  -      |        -             |      -
     * Optional | plugin  | all analyzer plugin  | unload only the specified
     *          |         | names                | plugin
     */
    void PUT_analytics_unload(endpointArgs);

191
192
193
194
195
196
197
198
199
200
201
    /**
     * PUT "/analytics/navigator"
     *
     * @brief Reloads the sensor navigator.
     *
     * Queries  | key     | possible values      | explanation
     * -------------------------------------------------------------------------
     * Required |  -      |        -             |      -
     */
    void PUT_analytics_navigator(endpointArgs);

202
    SensorCache*         _sensorCache;
203
    SensorDataStore*     _sensorDataStore;
204
    AnalyticsController* _analyticsController;
205
    SimpleMQTTServer* _mqttServer;
206
    std::map<std::string, influx_t> _influxMap;
207
208
209
};

#endif /* COLLECTAGENT_CARESTAPI_H_ */