SOLR Index 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 Dokumenten des SOLR Index und verwendbarer Authentifizierungs-Schnittstelle inklusive Beispiele. 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:

SOLR API Examples.postman_collection.json

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:

SOLR Index REST API

Ein SOLR-Index ist keine klassische Datenbank, sondern eine für die Suche optimierte, schreibgeschützte Datenablage. Daten werden über einen Prozess namens Indexierung hinzugefügt und stehen dann für blitzschnelle Abfragen zur Verfügung, insbesondere für komplexe Volltextsuchen. Anstatt zu speichern, welche Wörter in einem Dokument vorkommen (Dokument → Wörter), speichert er, in welchen Dokumenten jedes einzelne Wort vorkommt (Wort → Liste von Dokumenten).

Kernkomponenten:

1. Dokumente: Der Index besteht aus einer Sammlung von Dokumenten. Jedes Dokument ist eine einzelne Informationseinheit, die durchsucht werden soll (z. B. ein Kurs, ein Katalog, ein Nutzerprofil).

2. Felder: Jedes Dokument besteht aus Feldern, die die eigentlichen Daten enthalten. Felder sind wie Spalten in einer Datenbanktabelle (z. B. title, description). Jedes Feld hat einen definierten Datentyp (Text, Zahl, Datum etc.).

3. Schema: Die Struktur der Dokumente und Felder (Feldnamen, Datentypen, Analyse-Regeln) wird durch ein Schema fest definiert.

Der Indexierungsprozess ist asynchron. Es ist entscheidend zu verstehen, dass Änderungen an einem SOLR-Index (Hinzufügen, Aktualisieren oder Löschen von Dokumenten) nicht sofort in den Suchergebnissen sichtbar sind.

SOLR Index im LMS

Im LMS können Einstellungen zu den verfügbaren SOLR-Indizes im gleichnamigen Navigationspunkt konfiguriert werden. Ein entsprechender Index kann aktiviert und deaktiviert werden, auch lässt sich bei manchen die Anzahl der vergangenen Monate an Daten einstellen, die für die Indexierung herangezogen werden sollen.

SOLR-Index-Schnittstelle

Das LMS stellt den folgenden Enpunkt zur Abfrage von indexierten Daten aus SOLR zur Verfügung:

Die Authentifizierung erfolgt wie bei der Report API über einen Authorization-Header entweder mit Basic oder Bearer Authentification.

Parametriesierung von SOLR Daten

Für komplexe SOLR-Abfragen mit zahlreichen Parametern ist die Verwendung eines POST-Requests die sauberere Alternative zu GET. Während bei GET die URL schnell unübersichtlich und schwer lesbar wird, können die Query-Parameter bei einem POST-Request übersichtlich in den Request-Body ausgelagert werden. Damit SOLR diese Parameter korrekt interpretiert, ist es entscheidend, den Content-Type Header auf application/x-www-form-urlencoded zu setzen.

Rückgabetyp

Der Rückgabetyp kann mit dem wt-Parameter gesetzt werden. Wird kein Rückgabetyp via Parameter festgelegt erfolgt die Antwort grundlegend im JSON-Format mit Einrückung für die bessere Lesbarkeit. SOLR unterstützt eine Vielzahl von Rückgabetypen:

Um eine Antwort lesbarer zu gestalten, kann die Ausgabe im JSON oder XML-Format mit folgendem Parameter mit Einrückungen formatiert werden:

Filter

q-Parameter

Der q-Parameter (für "Query") bildet die Hauptsuche. Er findet relevante Dokumente und bewertet sie nach Relevanz (Score). Die grundlegendste Suche besteht darin, ein oder mehrere Wörter anzugeben. SOLR sucht dann in dem konfigurierten Standard-Suchfeld (oft ein kombiniertes Feld aus Titel, Beschreibung etc.) nach Dokumenten, die diese Wörter enthalten. Es kann nur ein q-Parameter in einer Anfrage enthalten sein:

fq-Parameter

Mit dem fq-Parameter (Filter Query) lassen sich die Suchergebnisse effizient einschränken. Der Hauptvorteil liegt in der Performance, da die Ergebnisse von Filter-Queries zwischengespeichert (gecached) werden. Obwohl q und fq eine identische Syntax verwenden, dienen sie fundamental unterschiedlichen Zwecken. Der fq-Parameter schränkt also die Dokumente ein, die für die Hauptsuche überhaupt in Frage kommen. Eine Anfrage kann im Gegensatz zum q-Parameter mehrere fq-Parameter enthalten. Durch die Unterstützung anderer Datentypen als Text gibt es weitere Filtermöglichkeiten: