Seit 2014 existiert die "alte" Version unserer REST-Schnittstellen. Grundsätzlich dienen diese Schnittstellen als Transportmittel und Kapselung für das generische HIT-Protokoll, in verschiedenen Ausprägungen für unterschiedliche Anwendungsszenarien angepasst.

Eine vollwertige REST-Schnittstelle ist nur bei HitCom verfügbar.

Einführung

Es gibt die oben aufgeführten verschiedenen Schnittstellen-Gruppen mit unterschiedlicher Zielsetzung und unterschiedlicher Nähe zum nativen HIT-Protokoll.

In der Regel sind die HTTP-Verben GET und POST implementiert, teilweise auch PUT und DELETE. Die Parameter beim GET sind gemäß HTTP-Spezifikation URL-encoded. Beim POST (und den anderen Verben) müssen die Formulardaten mittels HTTP-Header Content-type: application/x-www-form-urlencoded oder Content-type: application/json übermittelt werden. Die Antwortdaten werden standardmäßig im JSON-Format geliefert.

Authentifizierung

HIT erlaubt keinen anonymen Zugriff auf seine Daten. Es ist grundsätzlich eine Anmeldung mit Betriebsnummer und Passwort, ggf. mit Mitbenutzerkennung, erforderlich.
Neben einer Authentifizierung mit einem Passwort als Anfrageparameter ist bei RESTv1 (derzeit) kein weiteres Verfahren (z.B. OAuth Access Token, HTTP Authorization Header, etc) möglich!

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.

Diese Abfolge Anmeldung, Anfragenverarbeitung und Abmeldung 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 sollte ein Cache verwendet werden, der entgegen des REST-Paradigma server-seitig eine angemeldete Benutzersitzung vorhält (nicht identisch mit einer klassischen Webanwendung-Session). Man erhält den Sitzungsschlüssel des Cache durch eine explizite Anforderung der Cache-Nutzung und muss in der Antwort der Anforderung abgegriffen und für weitere Anforderungen verwendet werden.

Die Angabe des Parameters session steuert das Cache-Verhalten der Sitzung (gilt nur für RESTv1!):

• session=0 verwendet keine Session und es wird immer eine Anmeldung mit den angegebenen Credentials durchgeführt.
• session=1 ohne Angabe eines secret erzeugt eine neue Session und liefert als resultSecret den Sitzungsschlüssel für weitere Anforderungen in diesem Benutzerkontext zurück. Weitere Anfragen müssen die Betriebsnummer und ggf. den Mitbenutzer mitsenden, jedoch nicht das Passwort. Der bei dieser Anfrage angegebene Timeout schränkt sowohl die Verweildauer der Sitzung als auch die der vorgehaltenen Verbindung zur Datenbank ein.
• session=1 mit Angabe eines zuvor erhaltenen secret verwendet die bestehende Sitzung ohne erneute Anmeldung weiter. Die Betriebsnummer und ggf. der Mitbenutzer muss dennoch mitgesendet werden, jedoch nicht das Passwort.
  Eine unbekannter Sitzungsschlüssel führt zu einem Fehler.
• session=-1 mit Angabe eines zuvor erhaltenen secret verwendet die bestehende Sitzung ein letztes Mal und beendet diese anschließend. Danach kann der Sitzungsschlüssel nicht mehr verwendet werden. Eine unbekannter Sitzungsschlüssel führt zu einem Fehler.

Die Anfrageparameter werden in der gegebenen Reihenfolge eingelesen und für jeden Parameter intern vervollständigt, z.B. ist ein timeout intern 300 und wird durch eine explizite Angabe überschrieben. Am Ende der "Einlese-Kette" müssen dann mindestens die Parameter für Betriebsnummer, Mitbenutzerkennung, Passwort vorliegen. Falls nicht, wird ein Fehler ausgegeben.

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 RESTv1-Schnittstelle verarbeitet nur bei der API HitCom die üblichen HTTP-Verben GET, POST, PUT und DELETE (siehe Protokoll-Spezifikation). Bei HitBatch und HitRaw legen sie lediglich das Übertragungsverfahren fest, mit der die Parameter an die REST-Schnittstelle gesendet werden, also nur GET und POST. Ob Daten gemeldet oder abgefragt werden, legt in HitBatch der Parameter befehl fest oder in HitRaw ist dieser Bestandteil des Parameters befehlspuffer.