Liste bekannter Personenkontexte

GET /personen-info

Liefert die Personenkontext-IDs der dem Dienst bekannten und derzeit aktiven Personenkontexte sowie gegebenenfalls den Löschzeitpunkt.

Der Aufruf dieses Endpunkts erfolgt immer im Kontext des Dienstes. Der Dienst authentisiert sich durch den Client Credentials Flow.

Die Anfrage muss mit HTTP-GET gestellt werden. Als Antwort erfolgt eine Liste aus Datenobjekten, welche jeweils die Struktur einer Antwort der API person-info haben, jedoch nur drei Daten-Attribute enthalten: pid, id und gegebenenfalls den Löschzeitpunkt.

Personen und Personenkontexte, welche in der Liste nicht aufgeführt sind, sind als gelöscht anzunehmen und alle lokalen Daten des Dienstes zu dieser Person und diesem Personenkontext sind zu löschen.

Bei der Auslieferung von /personen-info wird im HTTP-Header ein ETag mitgeliefert. Bei nachfolgenden Abrufen der Personen-Information vom Schulconnex-Service kann der Dienst ein „If-None-Match“ Tag mit diesem ETag in den Request-Header mit aufnehmen.

Hat sich der Datensatz seit Auslieferung des ETag-Headers nicht geändert, so antwortet der Server mit einem Status 304 (Not Modified) und sendet den Datensatz nicht erneut.

Die Personenkontext-ID id ist die für den jeweiligen Dienst individuell pseudonymisierte ID des Personenkontexts.

Die Schnittstelle /personen-info ermöglicht das Verwenden eines Filterparameters zum Auslesen der vollständigen Datensätze der gelisteten Personen oder Personenkontexte im selben Umfang, wie sie auch bei /person-info geliefert werden.

Der Filter vollstaendig kann die Werte personen, personenkontexte, organisationen, gruppen oder beziehungen annehmen. Mehrere Werte können, getrennt durch Kommas, in einem Filter genutzt werden.

Zu beachten ist hierbei, dass bei Objekt-Hierarchien untergeordnete Objekte nur dann ausgegeben werden, wenn auch die in der Hierarchie direkt darüber liegenden Objekte ausgegeben werden. So werden bei der Auswahl von vollstaendig=personen,organisationen Informationen zu den Organisationen nicht mit ausgegeben, da diese nicht Teil von personen sind, sondern von personenkontexten. Sollen Informationen zu Organisationen mit ausgegeben werden, so ist als Filter vollstaendig=personen,personenkontexte,organisationen zu benutzen.

Darüber hinaus kann auch eine Filterung nach Personen, Personenkontexten, Gruppen und Organisationen anhand der jeweiligen ID erfolgen.

Welche Filterfunktionen genutzt werden können, wird durch eine vertragliche Absprache zwischen Dienstanbieter und Betreiber des Schulconnex-Servers geregelt.

Entsprechen keine Werte den angegebenen Filtern, so wird als Resultat eine leere Liste geliefert.

Filter	Typ	Parameter	Beschreibung
`vollstaendig`	String	`personen`	Möglichkeit, statt nur der `pid` zu jeder der gelisteten Personen die vollständige Beschreibung nach Datenmodell Person für Dienstanbieter, anzuzeigen.
		`personenkontexte`	Möglichkeit, statt nur `id` und `loeschung` zu jedem der gelisteten Personenkontexte die vollständige Beschreibung nach Datenmodell Personenkontext für Dienstanbieter, anzuzeigen.
		`gruppen`	Möglichkeit, statt nur der Gruppen-ID zu jeder gelisteten Gruppe die vollständige Beschreibung nach Datenmodell Gruppe für Dienstanbieter anzuzeigen.
		`organisationen`	Möglichkeit, statt nur der Organisations-ID zu jeder gelisteten Organisation die vollständige Beschreibung nach Organisation anzuzeigen.
		`beziehungen`	Möglichkeit, die Beziehungen, welche aus einem Personenkontext heraus bestehen, aufzulisten Es werden nur die `hat_als` Beziehungen ausgegeben. Der Default ist keine Ausgabe von Beziehungen.
`pid`	String		Mit diesem Filter kann der Datensatz einer einzelnen Person anhand ihrer `pid` ausgelesen werden.
`personenkontext.id`	String		Mit diesem Filter kann der Datensatz einer einzelnen Person mit einem einzelnen Personenkontext anhand der Kontext-ID ausgelesen werden. Die Informationen zur entsprechenden Person werden, unter Berücksichtigung des Filters `vollstaendig`, entsprechend der Client-Berechtigungen ausgeliefert.
`gruppe.id`	String		Mit diesem Filter können die Datensätze aller Personen ausgegeben werden, welche einer Gruppe zugeordnet sind. Die Informationen zur entsprechenden Person werden, unter Berücksichtigung des Filters `vollstaendig`, entsprechend der Client-Berechtigungen ausgeliefert. Es ist abhängig vom Schulconnex-Server, ob alle existierenden Personen der Gruppe mit aufgeführt werden oder nur solche, welche schon von dem Dienst abgerufen wurden und damit dem Dienst bekannt sind.
`organisation.id`	String		Mit diesem Filter können die Datensätze aller Personen ausgegeben werden, welche einer Organisation zugeordnet sind. Die Informationen zur entsprechenden Person werden, unter Berücksichtigung des Filters `vollstaendig`, entsprechend der Client-Berechtigungen ausgeliefert. Es ist abhängig vom Schulconnex-Server, ob alle existierenden Personen einer Organisation mit aufgeführt werden oder nur solche, welche schon von dem Dienst abgerufen wurden und damit dem Dienst bekannt sind.

Liste bekannter Personenkontexte

/personen-info

Request​

Responses​

Request

Responses