Schulconnex-Dienste-API

Dienste (Anwendungen) nutzen die Schulconnex-Dienste-API zum Abruf von Nutzer- und Kontextdaten.

Ein Zugriff auf die API ist in drei unterschiedlichen Sicherheitskontexten möglich:

Aufruf im Sicherheitskontext einer angemeldeten nutzenden Person mit Zugriff auf den Personenkontext, mit dem die Person angemeldet ist. Bei dieser Art des Zugriffs werden nur die Daten, die sich auf den konkreten Personenkontext beziehen, mit dem die oder der Nutzende angemeldet ist, durch die REST-API bereitgestellt. Dies ist der Standard-Zugriff für Dienste. Dieser Zugriff setzt einen Authentifizierungs- und Autorisierungsvorgang des oder der Nutzenden durch den Server voraus, bei dem ein entsprechender Access-Token für den Zugriff auf den Endpunkt ausgestellt wird.

Aufruf im Sicherheitskontext einer angemeldeten Person mit Zugriff auf alle Personenkontexte der Person. Nur angemeldeten Personen mit besonderem Vertrauensstatus kann es ermöglicht werden, auf die vollständigen Daten einer Person (alle Personenkontexte) zuzugreifen. Dieser Zugriff setzt ebenfalls einen Authentifizierungs- und Autorisierungsvorgang des oder der Nutzenden durch den Server voraus, bei dem ein entsprechender Access-Token für den Zugriff auf den Endpunkt ausgestellt wird.

Aufruf im Sicherheitskontext des Dienstes mit Zugriff auf alle Daten, die für sie freigegeben sind. Diese Art des Zugriffs erlaubt den Diensten eine (periodische) Synchronisierung der bei ihnen gehaltenen Daten mit den Daten des Schulconnex-Services, ohne dass sich die nutzenden Personen aktiv anmelden müssen. Der Zugriff erfolgt mit einem Access-Token, den der Authentifizierungsserver und Autorisierungsserver für den Dienst ausstellt. Dieser Sicherheitskontext wird aktuell zum periodischen Abgleich von gelöschten Daten verwendet.

Leere Inhalte in JSON-Antworten

Schulconnex-Server dürfen keine JSON-Objekte ohne Inhalte ausliefern.

Dies gilt sowohl für einzelne Attribute, für die kein Wert in der Antwort ausgeliefert wird, als auch für Arrays, die keine Elemente enthalten, und auch für komplexe JSON-Objekte, welche nur Attribute oder Unter-Objekte ohne Inhalte enthalten.

Ein einzelnes Attribut hat dann keinen Wert, wenn dieser nie gesetzt wurde und in der Spezifikation kein Default-Wert definiert ist, oder wenn ein vorhandener Wert gelöscht oder bei einem PATCH auf null gesetzt wurde. Unabhängig davon, ob ein Client im Prinzip auf dieses Attribut zugreifen kann, dürfen solche Attribute von Schulconnex-Servern nicht ausgeliefert werden.

Dies gilt auch für komplexe JSON-Objekte, wenn alle enthaltenen, für einen Client lesbaren, Attribute leer sind.

Ist, beispielsweise, zur Geburt einer Person nur der Ort und nicht das Datum gesetzt, so liefert der Server in der Antwort auch nur:

"geburt": {
      "geburtsort": "Berlin, Deutschland"
    }

Ist auch der Geburtsort nicht gesetzt, so wird das Objekt geburt in der Antwort nicht geliefert.

Hat ein Dienst nur Zugriff auf das Attribut geburt.datum, so darf das Objekt geburt in beiden Fällen nicht geliefert werden.

Hierdurch sollen Inkonsistenzen im Verhalten unterschiedlicher Schulconnex-Server vermieden werden und verhindert werden, dass Dienste implizit Rückschlüsse auf für diese nicht vertraglich freigegebene Attribute ziehen können.

Eine Ausnahme von diesem Verhalten besteht bei der Nutzung von Filtern beim Lese-Zugriff auf Daten. Wird, beispielsweise durch die Nutzung von Filtern, auf eine Anfrage kein Rückgabewert geliefert, so muss ein Schulconnex-Server eine leere Liste [] liefern.