Plan B API (1.4.11)
Plan B verfügt über ein paar Endpunkte, um Zugriff für andere Apps zu ermöglichen, z.B. MacStupas5.
Die API ist in weiterer Entwicklung. Ziel ist es, für jedes Datenmodell einen eigenen Endpunkt zu haben, mit den üblichen CRUD Operationen (POST, GET, PATCH, DELETE).
Wichtig: Um die Abwärtskompabilität zu wahren, werden die neuen Endpunkte unter /v3 eingeführt. Die alten Endpunkte bleiben unter /v2 bestehen. Da einige Endpunkte in beiden Versionen existieren werden sind diese ggf. unter /v2 und unter /v3 erreichbar. Dabei müssen sich die Endpunkte in /v3 nicht unbedingt an die Struktur und das Verhalten der Endpunkte in /v2 halten. Dies wird beim jeweiligen Endpunkt dokumentiert. Geplant ist es, die /v2 Endpunkte in den nächsten Versionen zu entfernen.
Als Datenschemata für die einzelnen Entitäten werden unterschiedliche Sichten verwendet:
- Eingabe: Die Daten, die für die Erstellung eines neuen Datensatzes verwendet werden, z.B.
kuerzel,vorname,nachname... bei Lehrern. Verknüpfte oder eingebettete Objekte werden per_idreferenziert (z.B.kursliste.lehrer._id) - Ausgabe: Die Daten, die bei einer GET Anfrage zurückgegeben werden. Bei Lehrern sind das die Eingabedaten, ergänzt um die
_idund die_groupId(ID der Schule). - Eingebettete Informationen: Um die Datenmenge bei GET Anfragen zu reduzieren, werden eingebettete Objekte nur mit wenigen Attributen zurückgegeben. So wird z.B. bei
kursliste.lehrernur die_idund daskuerzelzurückgegeben. Die vollständigen Daten können über einen eigenen GET Endpunkt abgefragt werden.
Der Events-Endpunkt liefert eine zusammengeführte Kalenderansicht aus mehreren Datenquellen. In diesem Ausgabemodell heißen die Kennungen der Events und Zeitsegmente id. Eine Event-ID ist nicht mit der _id eines Stammdatensatzes gleichzusetzen; die Lehrer-ID im Anfragepfad bleibt dagegen die _id aus den Lehrerstammdaten. Verknüpfte Datensätze werden über das optionale events[]._actionRef identifiziert. Der Events-Endpunkt beschreibt die Quelltypen und den Weg vom Unterrichts-Event über die Setzung zum Kurs und zur Kursliste.
GET Anfragen können mit Query Parametern gefiltert werden. So können z.B. alle Lehrer einer Klasse abgefragt werden oder alle Kurse eines Lehrers. Wir orientieren uns hierbei an den Empfehlungen von JSON:API.
Als Optionen können die Resultate paginiert werden. Hierbei wird die Anzahl (limit) der zurückgegebenen Datensätze und der Offset (skip) angegeben. Die serverseitige Sortierung der Ergebnisse erfolgt nach dem Standardverhalten von MongoDB durch Angabe eines Sortierfeldes sort und der Sortierrichtung.
Bei Listenendpunkten mit options liegt das default limit bei 1000 Datensätzen. Der Offset ist standardmäßig 0. Maßgeblich sind die beim jeweiligen Endpunkt dokumentierten Parameter. Der Events-Endpunkt verwendet ausschließlich einen Datumsbereich und liefert diesen vollständig; options[limit], options[skip] und Cursor zum Nachladen werden dort nicht unterstützt.
Beispiel: /api/v3/schueler?options[limit]=100&options[skip]=200&options[sort][vorname]=1&options[sort][geburtsdatum]=-1
Einige POST und PATCH Anfragen erfordern ggf. aufwändigere Verarbeitungsschritte. Diese werden asynchron im Hintergrund bearbeitet, indem sie in eine Jobqueue ausgelagert werden. Beispielsweise können bei der Erstellung einer Schüler-Absenz optional auch die Fehlstunden generiert werden. Die Generierung von Fehlstunden für Schüler einige Zeit in Anspruch nehmen.
In diesem Fall wird ein Job erstellt, der den Status der Verarbeitung enthält. Über einen eigenen Endpunkt können die Details zu einem Job abgefragt werden. Diese Anfragen enden mit dem Status 202. Im Response Header unter Location die relative URL übermittelt, unter der der Job abgefragt werden kann. Hier ist ggf. der Fortschritt und auch das Ergebnis des Jobs enthalten.