Abfrage von Report-Daten via REST-API

Einleitung

Dieser Artikel beschreibt grundlegend die Funktionsweise und Mechanismen einer REST-API und gibt anschließend einen Überblick zu den im LMS vorliegenden Implementierungen zur Abfrage von Reportdaten und den dazu notwendigen Hilfs- und Authentifizierungs-Schnittstellen inklusive Beispiele. Die Abfrage von Report-Daten via API ist für alle On-Screen Reports möglich, nicht jedoch für Standard-Reports und solche, die via Report Designer erstellt wurden.

Die folgenden Kapitel bieten eine grundlegende Einführung in die Architektur von REST-APIs. Sollten Sie mit diesen Thematiken bereits vertraut sein, empfehlen wir Ihnen, direkt zum Abschnitt REST-API des LMS zu springen, um mit den für Sie relevanten Informationen zu beginnen.

Über REST-API

Eine Representational State Transfer (REST) API ist ein architektonischer Stil zur Gestaltung von Netzwerkanwendungen. Sie basiert auf den etablierten Standards des World Wide Web und verwendet das HTTP-Protokoll für die Kommunikation. Der Kerngedanke von REST ist die Interaktion mit Ressourcen, wobei jede Ressource über eine eindeutige URI (Uniform Resource Identifier) identifizierbar ist. Die Kommunikation zwischen Client und Server erfolgt zustandslos, was bedeutet, dass jede Anfrage alle notwendigen Informationen enthält und der Server keinen Client-Kontext zwischen den Anfragen speichern muss. Als Datenformat für den Austausch wird überwiegend JSON (JavaScript Object Notation) verwendet, da es leichtgewichtig und für Mensch und Maschine einfach lesbar ist. Die konsequente Nutzung von Standard-HTTP-Methoden wie GET, POST, PUT und DELETE macht REST-APIs intuitiv, flexibel und skalierbar, was sie zur bevorzugten Wahl für moderne Web-Services macht.

Get

Die GET-Methode ist eine der grundlegendsten und am häufigsten verwendeten HTTP-Request-Methoden im Rahmen einer REST-API. Ihr primärer Zweck ist das Abrufen von Daten von einer spezifizierten Ressource. Eine GET-Anfrage ist per Definition sicher und idempotent, was bedeutet, dass sie den Zustand der Ressource auf dem Server nicht verändern darf und mehrfache identische Anfragen zum selben Ergebnis führen wie eine einzige. Parameter zur Filterung, Sortierung oder Paginierung der abgerufenen Daten werden üblicherweise als Query-Parameter an die URI angehängt. Bei einer erfolgreichen Anfrage antwortet der Server typischerweise mit dem HTTP-Statuscode 200 OK und liefert die angeforderten Daten im Body der Antwort, meist im JSON-Format.

Authorization Header

Der Authorization Header ist ein standardisierter HTTP-Header, der zur Authentifizierung eines Clients gegenüber einem Server dient. Er ermöglicht es dem Client, seine Identität oder
Berechtigung nachzuweisen, um auf geschützte Ressourcen zugreifen zu können. Der Header enthält die Anmeldeinformationen (Credentials) in einem erweiterbaren Schema. Die Struktur besteht aus dem Typ der Authentifizierungsmethode (z. B. Basic, Bearer) gefolgt von den eigentlichen Credentials. Die korrekte Implementierung des Authorization Headers ist entscheidend für die Sicherheit einer API, da er sicherstellt, dass nur autorisierte Parteien auf sensible Daten und Funktionalitäten zugreifen können.

Basic Authentication

Basic Authentication ist ein einfaches Authentifizierungsschema, das im HTTP-Standard definiert ist. Bei diesem Verfahren sendet der Client den Benutzernamen und das Passwort in einer einzigen, mit Base64-kodierten Zeichenkette im Authorization Header. Das Format lautet Authorization: Basic <base64-credentials>, wobei <base64-credentials> die Base64-Kodierung von username:password ist. Obwohl dieses Schema weit verbreitet und einfach zu implementieren ist, bietet es keine hohe Sicherheit, da Base64 leicht dekodiert werden kann. Aus diesem Grund darf Basic Authentication ausschließlich in Verbindung mit einer verschlüsselten Verbindung wie HTTPS/TLS verwendet werden, um das Abfangen der Anmeldeinformationen durch Dritte zu verhindern.

Bearer Authentication

Bearer Authentication (auch Token Authentication genannt) ist ein modernes und sicheres Authentifizierungsschema, das häufig in Verbindung mit OAuth2 und OIDC verwendet wird. Anstatt bei jeder Anfrage Benutzername und Passwort zu senden, authentifiziert sich der Client einmalig bei einem Autorisierungsserver und erhält im Gegenzug ein Zugriffstoken (Bearer Token). Dieses Token wird anschließend bei jeder Anfrage an die geschützte API im Authorization Header mit dem Schema Bearer mitgesendet. Der Name "Bearer" (dt. "Inhaber") impliziert, dass jeder, der im Besitz des Tokens ist, Zugriff erhält. Daher ist es essenziell, diese Tokens sicher zu behandeln und ausschließlich über verschlüsselte Verbindungen zu übertragen.

Bearer Token

Ein Bearer Token ist eine kryptografische Zeichenkette, die als Berechtigungsnachweis in der Bearer Authentication dient. Dieses Token wird von einem Autorisierungsserver ausgestellt, nachdem sich ein Client erfolgreich authentifiziert hat. Es repräsentiert die Berechtigung, im Namen eines Nutzers auf bestimmte Ressourcen zuzugreifen. Bearer Tokens sind in der Regel kurzlebig, um das Sicherheitsrisiko bei einem Diebstahl zu minimieren. Oft handelt es sich um JSON Web Tokens (JWT), die neben der Zugriffsberechtigung auch Informationen (Claims) über den Nutzer und die Gültigkeitsdauer enthalten können. Der Client muss das Token für die Dauer seiner Gültigkeit speichern und bei jeder Anfrage an einen geschützten Endpunkt im Authorization Header mitsenden.

Path Parameter

Path Parameter sind variable Bestandteile des URL-Pfads und dienen dazu, eine spezifische Ressource innerhalb einer Sammlung eindeutig zu identifizieren. Sie werden direkt in die URI-Struktur des Endpunkts eingebettet, typischerweise gekennzeichnet durch geschweifte Klammern, wie z.B. /users/{userId}. Um auf eine konkrete Ressource zuzugreifen, ersetzt der Client diesen Platzhalter durch einen tatsächlichen Wert, beispielsweise /users/123. Path Parameter sind in der Regel obligatorisch, da sie ein wesentlicher Bestandteil zur Bestimmung der angeforderten Ressource sind. Sie eignen sich ideal für den Zugriff auf ein einzelnes, eindeutiges Datenelement.

Query Parameter

Query Parameter sind Schlüssel-Wert-Paare, die am Ende einer URL angehängt werden, um die von einem Endpunkt zurückgegebene Datenmenge zu modifizieren. Sie werden durch ein Fragezeichen (?) vom Pfad getrennt und durch ein kaufmännisches Und (&) voneinander getrennt, z. B. /articles?status=published&sort=desc. Im Gegensatz zu Path Parametern, die eine Ressource identifizieren, dienen Query Parameter typischerweise zur Filterung, Sortierung oder Paginierung einer Ressourcen-Sammlung. Sie sind in der Regel optional und bieten dem Client eine flexible Möglichkeit, die Antwort des Servers nach seinen spezifischen Anforderungen zu gestalten, ohne dafür einen neuen Endpunkt definieren zu müssen.

POST

Die POST-Methode ist eine zentrale HTTP-Request-Methode, die hauptsächlich dazu verwendet wird, Daten an einen Server zu senden, um eine neue Ressource zu erstellen. Im Gegensatz zur GET-Methode, bei der Parameter in der URL übergeben werden, transportiert eine POST-Anfrage die zu übermittelnden Daten (die sogenannte Payload) im Body der Anfrage. Eine wesentliche Eigenschaft von POST ist, dass die Methode weder sicher noch idempotent ist. Das bedeutet, sie verändert den Zustand auf dem Server und das mehrfache Ausführen derselben POST-Anfrage führt in der Regel zur Erstellung mehrerer neuer Ressourcen. Bei erfolgreicher Erstellung antwortet der Server typischerweise mit dem HTTP-Statuscode 201 Created. Zusätzlich enthält die Antwort häufig einen Location-Header, der die URI der neu erstellten Ressource angibt, und kann im Body eine Repräsentation des neuen Objekts zurückgeben.

url-form-encoded

application/x-www-form-urlencoded ist ein Medientyp (MIME-Type), der zur Kodierung von Daten verwendet wird, die von einem Client an einen Server gesendet werden, typischerweise im Body einer POST-Anfrage. Dieses Format ahmt die Art und Weise nach, wie ein HTML-Formular seine Daten übermittelt. Die Daten werden als eine Zeichenkette von Schlüssel-Wert-Paaren strukturiert, wobei jedes Paar durch ein Gleichheitszeichen (=) getrennt und die einzelnen Paare durch ein kaufmännisches Und (&) verbunden sind. Sonderzeichen innerhalb der Schlüssel und Werte werden prozentkodiert (Percent-Encoding), um eine korrekte Übertragung und Interpretation sicherzustellen. Um diesen Datentyp zu verwenden, muss der Client den Content-Type-Header der HTTP-Anfrage auf application/x-www-form-urlencoded setzen. Obwohl in modernen REST-APIs häufig JSON (application/json) für die Übertragung komplexer Daten bevorzugt wird, bleibt url-form-encoded ein gängiger Standard, insbesondere für einfache Formularübermittlungen und in OAuth2-Flows, wie z.B. bei der Anforderung von Tokens.

REST-API des LMS

In den folgenden Abschnitten werden die Endpunkte zur Abfrage von Reportdaten vorgestellt. Des weiteren wird auch die Vorgehensweise für die korrekte Authentifizierung, Filterung, Sortierung, Pagination und Sprachauswahl erläutert. Im Zuge der Erläuterungen wird oft der Platzhalter <baseUrl> verwendet. In diesen muss die URL zum LMS bis zur Top-Level-Domain (.com/.de) angegeben werden.

Für alle in den kommenden Abschnitten genannten Schnittstellen liegt eine Postman-Collection mit praktischen Beispielabfragen zum Download für Sie bereit:
Report API examples.postman_collection.json

Report-Schnittstellen

Das LMS bietet im Kontext von Reports einige Schnittstellen an.

Die Antwort kann sowohl in XML als auch JSON gesendet werden, eine Auswahl geschieht dabei über den Accept-Header:

Authentication

Eine Möglichkeit der Authentifizierung an einer solchen Schnittstelle ist die Basic Authentication. Dafür müssen allerdings immer der Nutzername und das Passwort mitgegeben werden. Nutzername und Passwort müssen dabei mit einem Doppelpunkt getrennt und Base64-codiert wie folgt in einen Header geschrieben werden:

Da bei der Basic Authentication immer Nutzer und Passwort übertragen werden müssen, bietet sich für einen sicheren Workflow deshalb die Authentifizierung mittels Bearer Token an. Für den Erhalt eines solchen Tokens muss zuerst eine POST-Anfrage an das IDM (Identity Management) des LMS gesendet werden. Die Schnittstelle dafür lautet:

Die Payload muss dabei vom Medientyp x-www-form-urlencoded sein.

Entsprechend ist noch der folgende Header notwendig:

Bei erfolgreicher Anfrage wird eine Antwort mit dem Status 201 Created zurückgegeben, welche dann das Bearer Token (access_token) enthält, welches für die Authentifizierung der anderen Schnittstellen genutzt werden kann. Die Expiry (expires_in) gibt dabei an, wie viele Sekunden ein Token ab Anfrage gültig ist.

{
  "refresh_token": “eyJra… ",
  "access_token": "eyJra…”,
  "token_type": "Bearer",
  "expires_in": 86400
}

Um sich nun erfolgreich an einer der genannten Schnittstellen zu authentifizieren ist es notwendig den folgenden Header hinzuzufügen:

Grundabfrage Reportdaten

Um die Datensätze eines Reports via REST-API zu erhalten kann die folgende Schnittstelle genutzt werden:

Neben dem Platzhalter <baseUrl> gibt es nun auch den Platzhalter <reportId>. An dieser Stelle ist die jeweilige ID des Reports als Pfad-Parameter einzutragen, dessen Daten man als authentifizierter Nutzer abrufen möchte.

Die ReportID kann auf mehrere Weisen ermittelt werden. Die einfachste Art ist das Auslesen aus dem Report-Manager im System, wo alle Reports gelistet sind. Weitere Möglichkeiten sind das Auslesen auf Code- und Datenbankebene, was durch unser Consulting-Team durchgeführt werden kann.

Das Ergebnis enthält bei erfolgreicher Abfrage einen count mit der Anzahl der enthaltenen Datensätze. Ebenfalls enthalten ist ein header-Objekt in dem die einzelnen Spaltennamen mit ID, Name und Datentyp stehen, sowie die Sortierspalten und die Sortierreihenfolge. Zuletzt gibt es noch ein rows-Objekt, in dem verschachtelt die Datensätze des Reports stehen als Kombination von SpaltenID und enthaltenem Wert.

{
  "count": 77,
  "header": {…},
  "rows": {…}
}

Diese Schnittstelle bildet die Grundlage zur Abfrage von Reportdaten, allerdings ist eine komplette Abfrage aller Daten nicht immer sinnvoll. Im nächsten Abschnitt werden deswegen Möglichkeiten der Parametrisierung vorgestellt.

Parametrisierung von Reportdaten

Die Ergebnismenge kann mit Hilfe verschiedener Parameter angepasst werden. In den folgenden Abschnitten finden sich die Vorgehensweisen für die Filterung, Sortierung, Spaltenauswahl, Sprachauswahl und Pagination.

Filter

Die Ergebnisse können mit der Hilfe von Filtern eingeschränkt werden. Die Möglichkeiten der Filterung sind dabei auf die bereits im Report existierenden Filter beschränkt. Die Angabe von Filtern lässt sich mittels Query-Parameter umsetzen:

Eine Reportdaten-Anfrage mit mehreren Filtern hat demnach das Format:

Ein Beispiel mit Filterung bei einem Kursfortschritt-Report:

Report Nummer 125 ist der Report Kursfortschritt (Administrator). Mit der Filterung nach courseBookingStatus=8 erhalten wir in der Ergebnismenge nur Einträge, die im Status Gebucht sind und mit time_mode=0 erhalten wir nur Kurse die terminabhängig sind.

Für das Filtern nach mehreren Werten können die Werte mit Komma voneinander getrennt werden:

Die FilterID kann mittels Nutzung des Metadaten-API-Calls in Erfahrung gebracht werden - Für diesen ist nur die ReportID notwendig:

In der Antwort sind dann immer FilterID, Name, Typ sowie Flags für die Sichtbarkeit und Mehrfachselektion enthalten.

{
  "id": "courseBookingStatus",  
  "name": "Course enrollment status",  
  "type": "SELECT",
  "hidden": false,
  "multiple": true  
}

Wichtige Hinweise zur Nutzung von Filtern:

Für Filter aus einer Nutzerliste muss statt einer FilterID für diesen der Attributname genutzt werden.

Filter aus einer Metatagliste müssen wie folgt angegeben werden:

In einigen Fällen kann es vorkommen, dass ein Filter für Zahlen definiert ist, in der Datenbank aber Text unterstützt. Entsprechend wir keine Fehlermeldung angezeigt, sollte der Wert des Filters fälschlicherweise keine Zahl sein.

Die Filterung nach Datum bzw. Zeitspanne muss immer einem bestimmten Format folgen:

Der Teil ,userdefined ist dabei streng notwendig und muss immer nach dem zweiten Datum hinzugefügt werden, andererseits funktioniert der Filter nicht. Zusätzlich haben viele Filter keine Zeitselektion, der Zeit-Part im Datum wird dann einfach ignoriert. Das %20 steht für einen Whitespace.

Sortierung

Die Sortierung ist nur für solche Spalten möglich, die standardmäßig in einem Report angezeigt werden. Auch dafür kann wieder die Metadaten-Schnittstelle genutzt werden. Beispiel für eine Sortierung:

Beispiel für eine Sortierung nach Nachnamen absteigend:

Spaltenauswahl

Mit dem fields-Parameter lassen sich die Spalten in der gesendeten Antwort einschränken oder erweitern. Die Spaltennamen können in der XML-Datei des Reports ausgelesen oder via Metadaten API-Call abgefragt werden:

Beispiel für eine Auswahl von Vor- und Nachname:

Sprachauswahl

Die präferierte Sprache kann via Accept-Language-Header gesetzt werden:

Es besteht auch die Möglichkeit, eine Gewichtung bei der Sprachauswahl anzugeben. Hier ein Beispiel:

Es wird dann jene unterstützte Sprache mit der höchsten Gewichtung zurückgegeben, in diesem Fall DE. Sollte DE aber nicht unterstützt werden, so wird EN-GB zurückgegeben.

Ausgaben-Limits/Pagination

Es besteht außerdem die Möglichkeit, die Abfrage mit einem Limit (limit) zu versehen, oder die Ergebnisse ab einem gewissen Startpunkt (startindex) aufzulisten. In Kombination können Reportdaten stückweise verarbeitet werden. Die maximale Anzahl an Einträgen, die pro Aufruf zurückgegeben werden, beträgt 50000. Dies kann je nach Systemkonfiguration abweichen. Sollten mehr Einträge vorliegen, so ist dies im count vermerkt, es wird aber höchstens die maximale Anzahl zurückgegeben.

Wichtige Hinweise zur Nutzung von Limit und Startindex:

• startindex ohne limit hat keine Auswirkungen

• limit=0 ist kein valider Parameterwert

• startindex>=count gibt keinen Fehler, nur eine leere Antwort

• der erste Eintrag hat den Index 0, entsprechend haben die ersten 10 Einträge den Index 0 bis 9

• startindex=0 ist kein valider Parameterwert

• startindex=1 schneidet den ersten Eintrag ab

Hier einige Beispiele: