Wenn man in einem Eingabefeld die F1-Taste drückt, öffnet sich eine separate Hilfeseite mit Erläuterungen zum entsprechenden Eingabefeld bzw. zur Eingabeseite. Ob diese Hilfeseite in einem searaten Fenster geöffnet wird oder im aktuellen kann im Benutzer- und Programm-Profil festgelegt werden.

Diese Seite wendet sich an Softwarehersteller, die HIT per REST-Service nutzen wollen.

REST Version 2

Version 3.2.20240611

Seit April 2019 steht die neue Version unserer REST-Schnittstellen bereit.

Es grundsätzlich zwei Arten von Funktionen

  1. Funktionen, die ohne Anmeldung benutzt werden können, z.B.
    • Prüfen einer Ohrmarke oder Betriebsnummer auf syntaktische Korrektheit
    • Umwandeln einer beliebig formatierten Ohrmarke oder Betriebsnummer in die numerische bzw. alphanumerische normierte Darstellungsform
    • Abfrage des DataDictionary, welches die Beschreibung der in der ZD verfügbaren Meldungen/Entitäten mit deren Spalten samt deren Strukturbeschreibungen enthält
  2. Funktionen, die nur mit Anmeldung benutzt werden können, z.B.
    • Einfügen mittels PUT, abfragen mittels GET, ändern mittels POST, stornieren mittels DELETE gemäß CRUD-Pattern im "Standard REST-Modell"
    • Einfügen, abfragen, ändern, stornieren mittels HIT-Abfragesyntax, aber strukturieren Daten
Details

Authentifizierung

HIT erlaubt keinen anonymen Zugriff auf seine Daten. Es ist grundsätzlich eine Anmeldung mit Betriebsnummer und PIN, ggf. mit Mitbenutzerkennung, erforderlich. Zusätzlich ist die Angabe eines Timeout notwendig, die angibt, wie lange eine authentifizierte Sitzung intern vorgehalten wird. Neben einer Authentifizierung mit einer PIN kann auch ein über unseren zentralen Anmeldedienst erhaltenes OAuth Bearer Token verwendet werden.

Da die REST-Schnittstelle auch innerhalb der Web-Anwendung für das Autovervollständigen von Benutzereingaben verwendet wird, wird auch geprüft, ob eine bestehende Webanwendungssitzung vorhanden ist. Falls ja, werden die Anmeldedaten verglichen und bei Übereinstimmung schließlich die bestehende Verbindung zur HIT-Datenbank verwendet. Falls nicht oder wenn keine Session vorhanden ist, wird eine neue Verbindung angelegt.

Jede REST-Kommunikation impliziert per Definition eine Zustandslosigkeit. Wegen der Authentifizierung muss daher bei jeder Anfrage die Anmeldeinformation mitgesendet werden. Serverseitig wird dann die Anmeldung vorgenommen, die Anfrage verarbeitet und abschließend wieder abgemeldet. Da so zwischen zwei Anfragen keine Zustände zwischengespeichert werden, ist die Zustandslosigkeit gegeben.

Dies wirkt sich insbesondere beim Melden von mehreren Datensätzen erheblich auf die Performance aus, weil jede Anmeldung interne Prüfungen vornimmt - für jeden Datensatz jeweils eine Anmeldung! Daher kann ein Cache verwendet werden, der entgegen des REST-Paradigma server-seitig eine angemeldete Benutzersitzung vorhält (nicht identisch mit einer klassischen Webanwendung-Session).

Dazu muss lediglich nach der ersten Anfrage der zurückgelieferte Wert des Sitzungsschlüssels (ähnlich einem Browser-Cookie) abgegriffen und bei jeder weiteren Anfrage zusammen mit Betriebsnummer und Mitbenutzerkennung mitgesendet werden. Mit einem eigenen DELETE-Aufruf kann am Ende der Verarbeitung eine bestehende Benutzersitzung sauber beendet werden. Der bei der ersten Anfrage angegebene Timeout schränkt sowohl die Verweildauer der Sitzung, als auch die der vorgehaltenen Verbindung zur Datenbank ein.

Die Anmeldeinformationen können auf drei Arten übermittelt werden:

  1. Als Query-String bei der Anfrage-URI mit den Schlüsseln bnr, mbn, pin, act, cid, cacheTimeout und cacheSecret
  2. die Anmeldedaten über die im HTTP-Protokoll vordefinierte Authorization-Kopfzeile, der jedoch nur bnr:mbn:pin (für Betriebsnummer, Mitbenutzerkennung und PIN) oder bnr:pin (für Betriebsnummer und PIN) enthält. Das Feld muss gemäß Spezifikation codiert werden (Schema Basic und Base64-codierter Wert). Die PIN muss immer gefüllt sein, selbst wenn der Sitzungsschlüssel zusätzlich gesendet wird es da anderweitig nicht möglich ist, eine alternative Sitzung zu erzeugen wenn der Client intern zu einem anderen Webserver geleitet wird!
    Bei der Verwendung eines OAuth Bearer Tokens wird das Schema Bearer mit dem vom Zentralen Anmeldedienst erhaltenen Access Token (Schlüssel act) verwendet.
  3. eigene HTTP-Kopfzeilen mit hit-bnr, hit-mbn, hit-pin, hit-timeout und hit-secret. Bei der Verwendung eines OAuth Bearer Tokens sind statt hit-pin die Schlüssel hit-oauth und hit-oauth-clientid zu verwenden.

Die Angaben werden in der gegebenen Reihenfolge eingelesen und für jeden Parameter vervollständigt. Am Ende der "Einlese-Kette" müssen dann mindestens die Parameter für Betriebsnummer, Mitbenutzerkennung, PIN (oder Bearer Token) und Timeout vorliegen. Falls nicht, wird ein Fehler ausgegeben. Auch bei der Verwendung des Bearer Tokens müssen zur Erhöhung der Sicherheit Betriebsnummer und Mitbenutzerkennung mitgeliefert werden (nicht die PIN!).
Mehrfach angegebene Parameter werden abgelehnt, d.h. wird z.B. die Betriebsnummer sowohl als QueryString als auch als Teil der Authorization-Kopfzeile gesendet, gibt es einen Fehler - auch, wenn sie identisch sind! Insbesondere bei der Authorization-Kopfzeile ist noch eine der beiden anderen Verfahren notwendig, um die fehlenden Parameter für Timeout und Sitzungsschlüssel mit zu übertragen.
Werden sowohl PIN als auch das Bearer Token angegeben, wird ebenfalls ein Fehler ausgegeben. Beim Bearer Token ist aus Sicherheitsgründen zusätzlich die Client-ID mitzuliefern, mit dem sich der Client beim Zentralen Anmeldedienst authentifiziert hat.

Die Angabe des Timeout steuert das Cache-Verhalten der Sitzung:

  • ohne Sitzungsschlüssel legt ein positiver Wert eine neue Sitzung mit der gegebenen Lebensdauer in Sekunden an. Der Wert wird sowohl für den Cache als auch für die Verbindung für die Datenbank übernommen. Steht eine Sitzung und werden mit dem Sitzungsschlüssel weitere Anfragen gesendet, hat die Angabe des Timeout keine Auswirkungen mehr und kann weggelassen werden.
  • ein negativer Wert legt keine neue Sitzung an. Der absolute Wert des Timeout wird dabei nur für die Anmeldung an der Datenbank verwendet.
  • Wird kein Timeout angegeben (und ohne Sitzungsschlüssel gearbeitet), dann wird ein interner negativer Timeout angenommen.

Nach erfolgreicher Anmeldung erhält man in der JSON-Antwort (unabhängig vom verwendeten Verb) einen Schlüssel namens cache_secret mit dem Sitzungsschlüssel, über den eine REST-Benutzersitzung identifiziert wird. Dieser Wert kann, wenn gewünscht, zusammen mit Betriebsnummer und MBN (ohne PIN!) als cacheSecret oder hit-secret (siehe oben) bei jeder weiteren Anfrage der aktuellen Sitzung mitgesendet werden.

Generell werden alle JSON-Antworten mit der Zeichencodierung UTF-8 geliefert - unabhängig davon, ob der HTTP-Client ein eigenes Accept-Encoding anfordert. Diese Angabe wird ignoriert.

HTTP-Verben und ihre Aktionen

Die REST-Schnittstelle verarbeitet die üblichen HTTP-Verben GET, POST, PUT und DELETE (siehe Protokoll-Spezifikation).

Diese repräsentieren jeweils eine Aktion auf der HIT-Datenbank:

HTTP-Verb GET Abfrage einer Entität anhand einer Bedingung.
Entspricht dem HITP-Befehl RS.
Erwartet zwei QueryString-Parameter columns für die gewünschten Ausgabespalten und condition für die Abfrage-Bedingung. Beide müssen im HIT-Protokoll-Format vorliegen (CSV-Format, die condition als an SQL angelehnte Abfragesprache). Da auch komplexe Abfragen mit sogenannten Newline- und Mixline-Funktionen möglich sind, erhält man als Antwort auch eine komplexe JSON-Struktur!
HTTP-Verb POST Melden eines oder mehrerer Datensätze mit 1..n Schlüssel-Wert-Paaren zum Einfügen.
Entspricht dem HITP-Befehl IS.
Als Routen-Parameter ist die Entität anzugeben, z.B. als POST /api/hit/ZUGANG und als HTTP-Nachricht entweder ein JSON-Objekt mit Spalten-Wert-Paaren oder ein JSON-Array mit mehreren JSON-Objekten mit Spalten-Wert-Paaren. Die Spaltenangaben müssen natürlich zur angegebenen Entität passen.
Als Antwort erhält man die Hinweis- und Fehlertexte des HIT-Servers.
HTTP-Verb PUT Melden eines oder mehrerer Datensätze mit 1..n Schlüssel-Wert-Paaren zum Aktualisieren (wenn Schlüsselfelder vorhanden) oder Einfügen (wenn Schlüsselfelder nicht vorhanden).
Entspricht dem HITP-Befehl XS.
Als Routen-Parameter ist die Entität anzugeben, z.B. als PUT /api/hit/ZUGANG und als HTTP-Nachricht entweder ein JSON-Objekt mit Spalten-Wert-Paaren oder ein JSON-Array mit mehreren JSON-Objekten mit Spalten-Wert-Paaren. Die Spaltenangaben müssen natürlich zur angegebenen Entität passen.
Als Antwort erhält man die Hinweis- und Fehlertexte des HIT-Servers.
HTTP-Verb DELETE Stornieren eines Datensatzes mit 1..n Schlüssel-Wert-Paaren.
Entspricht dem HITP-Befehl SS.
Erlaubt auch das Beenden einer REST-Benutzersitzung.
Als Routen-Parameter ist die Entität anzugeben, z.B. als DELETE /api/hit/ZUGANG und als HTTP-Nachricht entweder ein JSON-Objekt mit Spalten-Wert-Paaren oder ein JSON-Array mit mehreren JSON-Objekten mit Spalten-Wert-Paaren. Die Spaltenangaben müssen natürlich zur angegebenen Entität passen.
Als Antwort erhält man die Hinweis- und Fehlertexte des HIT-Servers.
Üblicherweise wird bei DELETE kein sogenannter entity-body mitgeschickt. Da in HIT jedoch (historisch bedingt) nicht mit Datensatz-Identifizierern, sondern mit Kombinationen aus Primärschlüssel-Feldern gearbeitet wird, kann so keine ID angegeben werden. Da deswegen mehrere Schlüssel-Wert-Paare angegeben werden müssen (statt nur eine ID), ist auch beim DELETE eine JSON-Struktur erforderlich, die als HTTP-Nachricht mitgeschickt werden muss!
Dies kann zu Problemen bei HTTP-Clients führen, die dies bei DELETE nicht unterstützen!
Als Feature kann mit DELETE /api/hit/session und den QueryStrings bnr, mbn und cacheSecret für Betriebsnummer, Mitbenutzerkennung und Sitzungsschlüssel eine vorhandene server-seitig zwischengespeicherte REST-Benutzersitzung sauber beendet werden.