Skip to content

Commit fe46895

Browse files
e-pettersson-ericssone-pettersson-ericsson
authored
Update curl documentation (#134)
Separated the table of endpoints to their own section to make it more easy for user to quickly find what they are looking for. Added links to EI back-end documentation in some places. Added missing endpoints in the documentation and corrected some spelling mistakes. Updated README and updated info about subscriptions endpoint
1 parent 34ca39e commit fe46895

File tree

1 file changed

+218
-52
lines changed

1 file changed

+218
-52
lines changed

‎wiki/markdown/Front-end_with_curl.md renamed to ‎wiki/markdown/curl-examples.md

Lines changed: 218 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,119 @@
11
# Curl Examples to front-end
22

3-
The front-end is accessible not only via the web GUI.
4-
53
## Introduction
64

7-
The front-end has a bridge functionality that is built in as a part of the front-ends web server and handles request coming from the web GUI towards any of the back-ends configured. The front-end may also be used by other tools such as CURL or any kind of program that can make HTTP(S) requests.
5+
The front-end has a bridge functionality that is built in as a part of the front-end's web server and handles requests coming from the web GUI towards any of the back-ends configured.
6+
The `/backend` endpoint is the only additional endpoint which does not exist in [Eiffel Intelligence backend](https://github.com/eiffel-community/eiffel-intelligence).
7+
The front-end may also be used by other tools such as CURL or any kind of program that can make HTTP(S) requests.
8+
Below are some examples of using CURL towards different endpoints, together with example responses.
9+
Most endpoints are also documented in the [Eiffel Intelligence backend repository](https://github.com/eiffel-community/eiffel-intelligence/tree/master/wiki/markdown)
10+
11+
#### Quick access to endpoints:
12+
* [/auth](#auth)
13+
* [/backend](#backend)
14+
* [/download](#download)
15+
* [/information](#information)
16+
* [/query](#query)
17+
* [/rules](#rules)
18+
* [/subscriptions](#subscriptions)
19+
20+
21+
## <a id="auth" /> /auth
22+
23+
<table>
24+
<tr>
25+
<th>Context Path</th>
26+
<th>Type</th>
27+
<th>Explanation</th>
28+
</tr>
29+
<tr>
30+
<td>/auth</td>
31+
<td>GET</td>
32+
<td>Check if LDAP security is enabled</td>
33+
</tr>
34+
<tr>
35+
<td>/auth/checkStatus</td>
36+
<td>GET</td>
37+
<td>Used to check the back-end status</td>
38+
</tr>
39+
<tr>
40+
<td>/auth/login</td>
41+
<td>GET</td>
42+
<td>Login to EI with a username and password</td>
43+
</tr>
44+
<tr>
45+
<td>/auth/logout</td>
46+
<td>GET</td>
47+
<td>Logout from EI</td>
48+
</tr>
49+
</table>
50+
51+
A curl call with the command:
52+
53+
curl -X GET http://localhost:8080/auth
854

9-
#### The front-end handles:
10-
* POST, PUT and GET requests
11-
* Default back-end
12-
* Input back-end
55+
Gives the response data `{"security":false}`. The `security` parameter would be true if LDAP was enabled.
56+
57+
It is also possible to login and logout using curl. The below command provides the `-u` flag followed by a username.
58+
59+
curl -X GET -H "Content-type: application/json" -u <user> localhost:8080/auth/login
60+
61+
It is possible to provide both username and password directly in the request, as seen below.
62+
63+
curl -X GET -H "Content-type: application/json" -u <user>:<password> localhost:8080/auth/login
64+
65+
More information and examples can be found in the [EI back-end documentation](https://github.com/eiffel-community/eiffel-intelligence/blob/master/wiki/markdown/Authentication.md)
66+
67+
68+
## <a id="backend" /> /backend
69+
70+
<table>
71+
<tr>
72+
<th>Context Path</th>
73+
<th>Type</th>
74+
<th>Explanation</th>
75+
</tr>
76+
<tr>
77+
<td>/backend</td>
78+
<td>GET</td>
79+
<td>Retrieves a json list of available back-end instances</td>
80+
</tr>
81+
<tr>
82+
<td>/backend</td>
83+
<td>POST</td>
84+
<td>Adds one back-end instance</td>
85+
</tr>
86+
<tr>
87+
<td>/backend</td>
88+
<td>DELETE</td>
89+
<td>Deletes a given backend instance</td>
90+
</tr>
91+
</table>
1392

1493
While the web GUI may use the back-end instances list and select different back-ends in an easy way, a user that uses the front-end without the included web GUI may need to specify a back-end URL. This may be done by adding a `backendurl` parameter to the request.
1594

1695
Note that for users where the front-end and back-end is running with the help of Tomcat there will be context paths used.
1796

18-
### Default back-end
97+
#### Default back-end
1998

20-
The front-end may have been setup with a default back-end, this means that if no back-end is specified when making a HTTP request to the front-end the default back-end will be used.
21-
If you want to see a list of back-ends and see if there is a default back-end set you may use the command:
99+
The front-end can be configured to use a default back-end, this means that if no back-end is specified when making a HTTP request to the front-end the default back-end will be used.
100+
If you want to see a list of back-ends and see if there is a default back-end set, you may use the command:
22101

23-
###### Normal curl command for get:
102+
###### Example GET request using curl:
24103

25-
curl -X GET http://*front-end-url*/*contect-path-if-any*/backend
104+
curl -X GET http://*front-end-url*/*context-path-if-any*/backend
26105

27-
###### Curl command for get with host, port using Tomcat:
106+
###### Example GET request using curl, with host, port using Tomcat:
28107

29108
curl -X GET http://localhost:8080/eifrontend/backend
30109

31-
###### Curl command using EI default settings:
110+
###### Example GET request using curl, with EI default settings:
32111

33112
curl -X GET http://localhost:8080/backend
34113

35114
The default back-end should have the key `defaultBackend` set to `true`. If the JSON list ends up empty there are no back-ends specified in the front-end. If there is no JSON object with the key set to true there is no default back-end.
36115

37-
You may see that in the list, all objects have a key `active` set to `true or false`, this key points to the back-end that acts as default, if no default back-end exist, the active should usually be the first object in the list.
116+
In the response list all objects have a key `active` set to `true` or `false`. This key reveals which back-end instance has been selected in the GUI. A curl commands shows the default back-end as the `active` one. If no default back-end exists, the active should usually be the first object in the list.
38117

39118
If the back-end list lacks a default back-end one may be added by using a HTTP POST request. The injected object should be specified in JSON and look like the example below.
40119

@@ -49,6 +128,7 @@ You may add a back-end using for example CURL:
49128

50129
__Note:__ `name` must be unique.
51130

131+
Only one back-end instance can be added at a time.
52132
Even with different names all elements must be unique, you may not have two or more elements with the same `host`, `port`, `contextPath` or `https` value, one of these three keys must be different. Only the `contextPath` key may be left empty.
53133

54134
###### Example of __valid__ back-end list:
@@ -74,10 +154,21 @@ Second entry has different `host`, third entry has different `port`, third entry
74154

75155
The second entry is invalid due to having the same name as the first entry. The third entry is invalid due to having the same value in all fields as the first entry.
76156

77-
### Specified back-end
157+
#### Deleting a back-end instance via curl
158+
159+
It is possible to delete a back-end instance using curl. The full JSON object has to be specified to identify which instance should be deleted. It is not possible to delete a default backend instance.
160+
161+
{"name":"My Back-End","host":"localhost","port":8090,"contextPath":"","https":false,"defaultBackend":false},
162+
163+
In the below command the JSON object is put in a file and sent along with the request.
164+
165+
curl -X DELETE --data @data.json localhost:8080/backend
166+
167+
168+
#### Specified back-end
78169
As a user of the front-end you may want to specify your own back-end URL if you do not want to use the default back-end.
79170
This is possible to do by injecting the back-end URL as a query parameter.
80-
The parameters key should be `backendurl` then enter the full HTTP URL you wish to use.
171+
The parameters key should be `backendurl` then enter the full HTTP URL you wish to use. This back-end instance does not have to be specified in the list of available instances.
81172

82173
An example of a way to add such parameter is below, note that the "?" indicates that parameters has been added to the front-end url.
83174
`localhost:8080` is the front-end url, and we want to access the context path /auth but on URL `http://127.0.0.1:8090/` that is the back-end we wish to use.
@@ -93,52 +184,76 @@ This way of entering the `backendurl` may be the easiest way. It works with GET,
93184

94185
Note: It is not possible to add the `backendurl` parameter as a JSON parameter.
95186

96-
## Endpoints bridged from front-end to back-End
187+
188+
## <a id="download" />/download
189+
97190
<table>
98191
<tr>
99192
<th>Context Path</th>
100193
<th>Type</th>
101194
<th>Explanation</th>
102195
</tr>
103196
<tr>
104-
<td>/auth</td>
197+
<td>/download/subscriptionsTemplate</td>
105198
<td>GET</td>
106-
<td>Check if LDAP security is enabled</td>
199+
<td>Downloads a template with several predefined subscriptions</td>
107200
</tr>
108201
<tr>
109-
<td>/auth/checkStatus</td>
202+
<td>/download/rulesTemplate</td>
110203
<td>GET</td>
111-
<td>Used to check the back-end status.</td>
204+
<td>Downloads a template with predefined rules</td>
112205
</tr>
113206
<tr>
114-
<td>/subscriptions</td>
207+
<td>/download/eventsTemplate</td>
115208
<td>GET</td>
116-
<td>Fetches all available subscriptions from the back-end</td>
117-
</tr>
118-
<tr>
119-
<td>/subscriptions</td>
120-
<td>POST</td>
121-
<td>Request to add a new subscription included as a JSON object</td>
209+
<td>Downloads a template with predefined events</td>
122210
</tr>
211+
</table>
212+
213+
The EI front-end supports these endpoints. More information can be found in the [EI back-end documentation](https://github.com/eiffel-community/eiffel-intelligence/blob/master/wiki/markdown/Download-Files.md)
214+
215+
#### Some curl examples
216+
217+
This command would return a list of rules.
218+
219+
curl -X GET -H "Content-type: application/json" http://localhost:8080/download/rulesTemplate
220+
221+
This command returns a list of predefined template events.
222+
223+
curl -X GET -H "Content-type: application/json" http://localhost:8080/download/eventsTemplate
224+
225+
This command returns a list of several subscriptions. It is also possible to specify a file in which to save the downloaded objects in to.
226+
227+
curl -X GET -H "Content-type: application/json" localhost:8080/download/subscriptionsTemplate --output myFile.json
228+
229+
230+
## <a id="information" />/information
231+
232+
<table>
123233
<tr>
124-
<td>/subscriptions</td>
125-
<td>PUT</td>
126-
<td>Request to update a given subscription object included as a JSON object</td>
234+
<th>Context Path</th>
235+
<th>Type</th>
236+
<th>Explanation</th>
127237
</tr>
128238
<tr>
129-
<td>/subscriptions/*subscription name*</td>
239+
<td>/information</td>
130240
<td>GET</td>
131-
<td>Fetches information about a single subscription from the back-end</td>
132-
</tr>
133-
<tr>
134-
<td>/subscriptions/*subscription name*</td>
135-
<td>DELETE</td>
136-
<td>Deletes a single instance from the back-end</td>
241+
<td>Fetches all information about the back-end and its components</td>
137242
</tr>
243+
</table>
244+
245+
This endpoint support `GET` requests, which returns information about EI back-end and connected components.
246+
The response is a json object containing all the connected components and data about them.
247+
248+
curl -X GET -H "Content-type: application/json" localhost:8080/information
249+
250+
## <a id="query" />/query
251+
252+
<table>
138253
<tr>
139-
<td>/information</td>
140-
<td>GET</td>
141-
<td>Fetches all information from about the back-end and its components</td>
254+
<th>Context Path</th>
255+
<th>Type</th>
256+
<th>Explanation</th>
142257
</tr>
143258
<tr>
144259
<td>/queryAggregatedObject</td>
@@ -152,18 +267,26 @@ Note: It is not possible to add the `backendurl` parameter as a JSON parameter.
152267
</tr>
153268
<tr>
154269
<td>/query</td>
155-
<td>GET</td>
156-
<td>Free style query; user specifies queries</td>
270+
<td>POST</td>
271+
<td>Free style query; user specified queries</td>
157272
</tr>
273+
</table>
274+
275+
Example curl commands to these endpoints [can be found here](https://github.com/eiffel-community/eiffel-intelligence/blob/master/wiki/markdown/Query.md) and [here](https://github.com/eiffel-community/eiffel-intelligence/blob/master/wiki/markdown/Query-aggregated-objects.md)
276+
277+
278+
## <a id="rules" />/rules
279+
280+
<table>
158281
<tr>
159-
<td>/query</td>
160-
<td>POST</td>
161-
<td>Free style query; user specifies queries</td>
282+
<th>Context Path</th>
283+
<th>Type</th>
284+
<th>Explanation</th>
162285
</tr>
163286
<tr>
164287
<td>/rules/rule-check/testRulePageEnabled</td>
165288
<td>GET</td>
166-
<td>TestRules status, is Test Rules functionality enabled in the back-end</td>
289+
<td>Check if TestRules is enabled in the back-end</td>
167290
</tr>
168291
<tr>
169292
<td>/rules/rule-check/aggregation</td>
@@ -172,21 +295,64 @@ Note: It is not possible to add the `backendurl` parameter as a JSON parameter.
172295
</tr>
173296
</table>
174297

175-
## Curl Examples
176-
A curl call with the command: `curl -X GET http://localhost:8080/auth` Gives the response data `{"security":false}`. The `security` parameter would be true if LDAP was enabled.
298+
For these endpoints to be reachable the Eiffel Intelligence back-end [needs to be configured](https://github.com/eiffel-community/eiffel-intelligence/blob/master/src/main/resources/application.properties) with `testaggregated.enabled: true`.
299+
The below command would result in a json response of `{"status":true}` if this functionality is enabled.
300+
301+
curl -X GET -H "Content-type: application/json" localhost:8080/rules/rule-check/testRulePageEnabled
302+
303+
304+
Example curl commands to these endpoints [can be found here](https://github.com/eiffel-community/eiffel-intelligence/blob/master/wiki/markdown/Running-rules-on-objects.md)
305+
306+
## <a id="subscriptions" />/subscriptions
307+
308+
<table>
309+
<tr>
310+
<th>Context Path</th>
311+
<th>Type</th>
312+
<th>Explanation</th>
313+
</tr>
314+
<tr>
315+
<td>/subscriptions</td>
316+
<td>GET</td>
317+
<td>Fetches all available subscriptions from the back-end</td>
318+
</tr>
319+
<tr>
320+
<td>/subscriptions</td>
321+
<td>POST</td>
322+
<td>Request to add one (or more) new subscription(s) included in JSON format</td>
323+
</tr>
324+
<tr>
325+
<td>/subscriptions</td>
326+
<td>PUT</td>
327+
<td>Request to update one (or more) subscription object(s) included in JSON format</td>
328+
</tr>
329+
<tr>
330+
<td>/subscriptions/*subscription name*</td>
331+
<td>GET</td>
332+
<td>Fetches information about a single (or multiple) subscription(s) from the back-end</td>
333+
</tr>
334+
<tr>
335+
<td>/subscriptions/*subscription name*</td>
336+
<td>DELETE</td>
337+
<td>Deletes a single (or multiple) subscription(s) from the back-end</td>
338+
</tr>
339+
</table>
340+
177341

178-
The `/subscriptions` endpoint is one that may be used the most, we may call that endpoint using three methods `GET`, `POST` and `PUT`.
342+
The `/subscriptions` endpoint can be called with `GET`, `POST`, `PUT` and `DELETE`.
343+
More information, and examples, on the `/subscriptions` API can be found [here](https://github.com/eiffel-community/eiffel-intelligence/tree/master/wiki/markdown/Subscription-API.md).
179344

180345
A `POST` request with subscriptions in a file may look as the following example.
181346

182347
curl -X POST -d @file_containing_list_of_json_objects -H "Content-Type: application/json" \
183348
http://localhost:8080/subscriptions?backendurl="http://127.0.0.1:8090/"
184349

185350
Here is an example using this endpoint and the result it gives in case we have the templated subscriptions added.
351+
The `backendurl` parameters is passed in to use a specified instance instead of the default back-end instance.
186352

187353
curl -X GET http://localhost:8080/subscriptions?backendurl="http://127.0.0.1:8090/"
188354

189-
The back-end used is running on localhost and port 8080, we redirect the request to 127.0.0.1 and port 8090 as requested in the query parameters and the result is as follows
355+
The back-end used is running on localhost and port 8080. EI front-end forwards the request to 127.0.0.1 and port 8090 as requested in the query parameters and the result is as follows:
190356

191357
[
192358
{

0 commit comments

Comments
 (0)