Schnittstelle - OpenSlides/OpenSlides GitHub Wiki

Schnittstelle für den Client

⚠️ Warnung

Die 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.

Beispiele mit Curl

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.

Abrufen von Daten durch den Client

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"}

Aufrufen spezieller Daten über den Backend-Presenter

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
        }
    }
]'

Schreiben der Daten über die Backend-Actions

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.

Beispiele

⚠️ **GitHub.com Fallback** ⚠️