elektra-web HTTP API #912
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,66 @@ | ||
| # elektra web | ||
|
|
||
| _a web user interface (Web UI) to remotely manage multiple elektra instances_ | ||
|
|
||
|
|
||
| ## Overview | ||
|
|
||
| Elektra web consists of multiple components: | ||
|
|
||
| * (multiple) servers running an elektra daemon (`elektrad`) | ||
| * a single cluster management server to communicate with the elektra daemons (`clusterd`) | ||
| * a client (web browser) that accesses the Web UI on the cluster management server | ||
|
|
||
|  | ||
|
|
||
|
|
||
| ## GUI | ||
|
|
||
| The Web UI allows the user to add new instances to the network, as well as | ||
| combine multiple instances into a cluster. If the configuration of a cluster is | ||
| edited, the changes are pushed to all instances in the cluster. Furthermore, | ||
| single instances can be configured independently. | ||
|
|
||
| The configuration view of elektra web is similar to the tree view of the | ||
| [qt-gui](https://github.com/ElektraInitiative/libelektra/tree/master/src/tools/qt-gui). | ||
|
|
||
|  | ||
|
|
||
|
|
||
| ## API | ||
|
|
||
|  | ||
|
|
||
| To access single instances, each elektra daemon (`elektrad`) provides a RESTful | ||
| HTTP API: | ||
|
|
||
| * **GET /version** - get `elektrad` version | ||
|
There was a problem hiding this comment. Which format? I would only return Elektra's and HTTP API's version, and not invent one for the tool. There was a problem hiding this comment. He didn't specify what the version is used for, so I didn't comment it so far. But you are right, version management could get easily a huge task that isn't really in scope of his work. There was a problem hiding this comment. I would make all responses in JSON by default. Later, we can allow adding a suffix, e.g. There was a problem hiding this comment. I would prefer to use something like |
||
| * **GET /kdb/:path** - get `path` configuration (similar to `kdb get path`) | ||
| * **POST /kdb/:path** - edit `path` configuration (similar to `kdb set path`) | ||
|
There was a problem hiding this comment. If it is similar, what are the differences, can you give examples? There was a problem hiding this comment. Right now, it actually just calls There was a problem hiding this comment. Yes, but we should discuss (and describe) how it should be, not like an implementation currently does. |
||
|
|
||
| The cluster management server (`clusterd`) also provides a RESTful HTTP API. | ||
| Single instances can be configured as follows: | ||
|
|
||
| * **GET /instances** - get a list of all instances | ||
| * **POST /instances** - create a new instance | ||
| * **GET /instances/:id** - get information about a single instance | ||
| * **POST /instances/:id** - edit a single instance | ||
|
There was a problem hiding this comment. For updating/patching you should use PUT or PATCH. There was a problem hiding this comment. Both PUT or PATCH make sense, but we cannot use json merge patch because in Elektra null and absent is something different. With put we might not need DELETE, if everything missing in PUT is deleted. There was a problem hiding this comment. I changed it to |
||
| * **GET /instances/:id/kdb** - get full configuration of an instance | ||
| * **GET /instances/:id/kdb/:path** - get `path` configuration of an instance (similar to `kdb get path`) | ||
| * **POST /instances/:id/kdb/:path** - edit `path` configuration of an instance (similar to `kdb set path`) | ||
| * **GET /instances/:id/version** - get `elektrad` version of an instance | ||
|
|
||
| It is also possible to create and manage groups of multiple elektra instances (clusters): | ||
|
|
||
| * **GET /version** - get `clusterd` version | ||
| * **GET /clusters** - get a list of all clusters | ||
| * **POST /clusters** - create a new cluster | ||
| * **GET /clusters/:id** - get information about a single cluster | ||
| * **POST /clusters/:id** - edit a single cluster | ||
|
There was a problem hiding this comment. Same as for the There was a problem hiding this comment. Can we generalize the API such that we do not need different API descriptions for There was a problem hiding this comment. Good idea, I removed the redundant API and added a note. |
||
| * **GET /clusters/:id/kdb** - get full configuration of a cluster | ||
| * **GET /clusters/:id/kdb/:path** - get `path` configuration of a cluster (similar to `kdb get path`) | ||
| * **POST /clusters/:id/kdb/:path** - edit `path` configuration of a cluster (similar to `kdb set path`) | ||
| * **GET /clusters/:id/version** - get list of `elektrad` versions of all instances in the cluster | ||
|
|
||
| Cluster configuration is stored on the cluster management server and persisted | ||
| to all instances. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think its better to remove the architecture parts from here and put them into an extra document as discussed. This document should only be about the HTTP API.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I disagree, because he references the architecture within his API description, so it should be known what he is talking about. The component description in this document isn't really extensive, so I don't see a problem at all. He could still write a lot more about it in another document, that is correct.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree that it would make sense to have a separate document that goes into details of the architecture. Here I'm just giving a small overview to make it easier to understand the API.