2024-04-10 21:36:55 +02:00
|
|
|
# Galene's administrative API
|
|
|
|
|
|
|
|
|
|
Galene provides an HTTP-based API that can be used to create groups and
|
|
|
|
|
users. For example, in order to create a group, a client may do
|
|
|
|
|
|
|
|
|
|
PUT /galene-api/0/.groups/groupname/
|
|
|
|
|
Content-Type: application/json
|
|
|
|
|
If-None-Match: *
|
|
|
|
|
|
|
|
|
|
The `If-None-Match` header avoids overwriting an existing group.
|
|
|
|
|
|
|
|
|
|
In order to edit a group definition, a client first does
|
|
|
|
|
|
|
|
|
|
GET /galene-api/0/.groups/groupname/
|
|
|
|
|
|
|
|
|
|
This yields the group definition and an entity tag (in the ETag header).
|
|
|
|
|
The client then modifies the group defintion, and does
|
|
|
|
|
|
|
|
|
|
PUT /galene-api/0/.groups/groupname/
|
|
|
|
|
If-Match: "abcd"
|
|
|
|
|
|
|
|
|
|
where "abcd" is the entity tag returned by the GET request. If the group
|
|
|
|
|
definition has changed in the meantime, the entity tag will no longer be
|
|
|
|
|
valid, and the server will fail the update, which avoids losing an update
|
|
|
|
|
in the case of a concurrent modification.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Endpoints
|
|
|
|
|
|
|
|
|
|
The API is located under `/galene-api/0/`. The `/0/` is a version number,
|
|
|
|
|
and will be incremented if we ever find out that the current API cannot be
|
|
|
|
|
extended in a backwards compatible manner.
|
|
|
|
|
|
|
|
|
|
### Statistics
|
|
|
|
|
|
|
|
|
|
/galene-api/0/.stats
|
|
|
|
|
|
|
|
|
|
Provides a number of statistics about the running server, in JSON. The
|
|
|
|
|
exact format is undocumented, and may change between versions. The only
|
|
|
|
|
allowed methods are HEAD and GET.
|
|
|
|
|
|
|
|
|
|
### List of groups
|
|
|
|
|
|
|
|
|
|
/galene-api/0/.groups/
|
|
|
|
|
|
|
|
|
|
Returns a list of groups, as plain text, one per line. The only allowed
|
|
|
|
|
methods are HEAD and GET.
|
|
|
|
|
|
|
|
|
|
### Group definition
|
|
|
|
|
|
|
|
|
|
/galene-api/0/.groups/groupname
|
|
|
|
|
|
|
|
|
|
Contains a "sanitised" group definition in JSON format, analogous to the
|
|
|
|
|
on-disk format but without any user definitions or cryptographic keys.
|
|
|
|
|
Allowed methods are HEAD, GET, PUT and DELETE. The only accepted
|
|
|
|
|
content-type is `application/json`.
|
|
|
|
|
|
2024-04-11 13:45:30 +02:00
|
|
|
### Fallback users
|
|
|
|
|
|
|
|
|
|
/galene-api/0/.groups/groupname/.fallback-users
|
|
|
|
|
|
|
|
|
|
Contains fallback user descriptions, in the same format as the
|
|
|
|
|
`fallbackUsers` field of the on-disk format. Allowed methods are PUT and
|
|
|
|
|
DELETE. The only accepted content-type is `application/json`.
|
|
|
|
|
|
2024-04-11 13:25:59 +02:00
|
|
|
### Authentication keys
|
|
|
|
|
|
|
|
|
|
/galene-api/0/.groups/groupname/.keys
|
|
|
|
|
|
|
|
|
|
Contains the keys used for validation of stateless tokens, encoded as
|
|
|
|
|
a JSON key set (RFC 7517). Allowed methods are PUT and DELETE. The only
|
|
|
|
|
accepted content-type is `application/jwk-set+json`.
|
|
|
|
|
|
2024-04-10 21:36:55 +02:00
|
|
|
### List of users
|
|
|
|
|
|
|
|
|
|
/galene-api/0/.groups/groupname/.users/
|
|
|
|
|
|
|
|
|
|
Returns a list of users, as plain text, one per line. The only allowed
|
|
|
|
|
methods are HEAD and GET.
|
|
|
|
|
|
|
|
|
|
### User definition
|
|
|
|
|
|
|
|
|
|
/galene-api/0/.groups/groupname/.users/username
|
|
|
|
|
|
|
|
|
|
Contains a "sanitised" user definition (without any passwords), a JSON
|
|
|
|
|
object with a single field `permissions`. Allowed methods are HEAD, GET,
|
|
|
|
|
PUT and DELETE. The only accepted content-type is `application/json`.
|
|
|
|
|
|
|
|
|
|
### Passwords
|
|
|
|
|
|
|
|
|
|
/galene-api/0/.groups/groupname/.users/username/.password
|
|
|
|
|
|
|
|
|
|
Contains the password of a given user. The PUT method takes a full
|
|
|
|
|
password definition, identical to what can appear in the `"password"`
|
|
|
|
|
field of the on-disk format, while the POST method takes a string which
|
|
|
|
|
will be hashed on the server. Allowed methods are PUT, POST and DELETE.
|
|
|
|
|
Accepted content-types are `application/json` for PUT and `text/plain` for
|
|
|
|
|
POST.
|
