Schnittstelle - OpenSlides/OpenSlides GitHub Wiki
⚠️ WarnungDie Schnittstelle existiert nur für den OpenSlides-Client. Eine Aufwärts- bzw. Abwärtskompatibilität wird nicht garantiert. Schnittstellen können bei Bedarf ohne Ankündigung geändert werden.
Der hier dokumentierte Stand bezieht sich auf OpenSlides 4.0.5.
Der Client kommuniziert mit dem OpenSlides-Server über verschiedene HTTP-Requests.
- Zunächst muss der Client über den Auth-Service sich authentifizieren.
- Anschließend können über den Autoupdate-Service Daten über ihre ID abgerufen und abonniert werden.
- Der Backend-Presenter bietet konkrete Abfragen an, die nicht performant über den Autoupdate-Service funktionieren würden.
- Über die Backend-Action können Daten geändert werden.
Alle Beispiele in der Beschreibung der Schnittstelle sind mit curl dargestellt. Zur besseren Lesbarkeit enthalten die Beispiele keine Auth-Tokens.
Bei Beispielen zum Abrufen von Daten über den Autoupdate-Service sind nur die Request-Bodies angegeben.
Die Daten von OpenSlides werden über den Autoupdate-Service abgerufen. Der Autoupdate-Service erwartet einen Request-Body im JSON-Format. Die Funktionsweise ist vergleichbar mit GraphQL. Die Daten von OpenSlides sind über Referenzen verbunden. Über das Request-Format ist es möglich den Referenzen zu "folgen". Die Anfrage muss jedoch immer bei einem konkreten Objekt mit einer bestimmten ID beginnen. Es ist über den Autoupdate-Service nicht möglich User oder andere Objekte anhand eines Feldes zu "suchen". Beispielsweise ist es nicht möglich einen Nutzer anhand seines Nutzernamens oder seiner E-Mail-Adresse abzurufen. Auch ein Abruf über die external-ID ist nicht möglich.
Das Format wird auf der Seite des Autoupdate-Service abstrakt beschrieben. Die möglichen Felder werden in der models.yml definiert.
Über das URL-Attribute single=true
wird das Request nach der Rückgabe beendet,
wie dies bei den meisten HTTP-Requests üblich ist. Wird das Attribut
weggelassen, dann bleibt die Verbindung offen. Ändern sich die angefragten
Daten, dann werden diese über die Verbindung gepusht.
Der Rückgabewert ist im json line format. Jede Zeile
ist ein JSON-Objekt mit Keys und Values. Ein Key ist eine sogenannte 'Full
Qualified ID'. Er besteht immer aus drei Teilen: Dem Namen der Collection, der
ID und dem Feldnamen. Die Teile werden durch ein /
getrennt. Zum Beispiel:
user/1/username
. Der Value ist der Wert des Feldes als JSON.
Angefragte Felder, die nicht existieren oder für die der anfragende Nutzer keine Rechte hat, werden in der Rückgabe ignoriert.
Eine Anfrage sieht zum Beispiel so aus:
curl -k https://localhost:8000/system/autoupdate?single=true -d '[{"collection":"user","ids":[1],"fields":{"username":null,"first_name":null,"last_name":null}}]'
Die Rückgabe sieht beispielsweise wie folgt aus:
{"user/1/last_name":"Administrator","user/1/username":"admin"}
Da Daten über den Autoupdate-Service nur über eine ID abgerufen werden können und das Autoupdate-Format keine Paginierung unterstützt, können spezielle Abfragen über den Presenter abgerufen werden.
Eine Liste der bestehenden Presenter findet sich auf Presenter-Service.
Die Daten werden über die URL /system/presenter/handle_request
abgerufen. Es
wird ein POST
Request mit einem JSON-Body erwartet. Beispielsweise:
curl -k -H "content-type: application/json" https://localhost:8000/system/presenter/handle_request -d '[
{
"presenter": "get_users",
"data": {
"start_index": 0,
"entries": 10,
"sort_criteria": ["first_name", "last_name"],
"reverse": false
}
}
]'
Die Daten von OpenSlides werden über das Backend verändert. Alle Änderungen
erfolgen über eine sogenannte Action. Jede Action wird an die URL
/system/action/handle_request
gesendet. Es wird ein POST
-Request mit einem
JSON-Body erwartet. Beispielsweise:
curl -k -H "content-type: application/json" https://localhost:8000/system/action/handle_request -d '[
{
"action": "user.create",
"data": [
{
"username": "new-user",
"default_password": "sicher",
"is_active": true
}
]
}
]'
Mit jedem Request können mehrere verschiedene Actions gesendet werden. Von jeder Action können mehrere Datensätze übergeben werden. Alle Actions in einem Request werden von OpenSlides als eine atomare Änderung betrachtet.
Eine Übersicht über alle Actions und deren Payload findet sich hier. Die Seite ist sortiert nach den Objekten, die bearbeitet werden können, und den zugehörigen Aktionen.
Die meisten Actions haben abgesehen von der Erfolgsmeldung keine Rückgabe. Die
geänderten Daten müssen über den Autoupdate-Service abgerufen werden. Bei
Create
-Actions wird die ID des neu angelegten Objekts zurückgegeben.
Über die Entwicklertools der Webbrowser können alle ausgehenden Requests betrachtet werden. Auf diese Weise lässt sich leicht feststellen, welche Action der OpenSlides-Client verwendet und welcher Payload gesandt wird.