|
| |
Allgemein - REST Version 2
 | Seit 1.April 2019 ist neue, komfortablere Version des REST-Services in
Betrieb |
| Schnittstellendefinitionen, Dokumentation und Testinterface gibt es
getrennt nach Anmelde- und Datenkontext für
|
Einführung in die Nutzung der Schnittstellen (API) HIT-REST v2
An den Endpunkten (REST-URL) der Version 2 ist sowohl die
alte API des REST Version 1 (Details unten) als auch die neue API Version 2 verfügbar.
Die neue API Version 2 gliedert sich grundsätzlich in zwei Arten von Funktionen
| einfache 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 |
|
| zugriffsbeschränkte Funktionen, die nur mit Anmeldung benutzt werden
können, z.B.
| Einfügen mittels PUT, abfagen mittels GET, ändern mittels
POST,
stornieren mittels DELETE gemäß CRUD-Pattern
(Standard-REST-Modell) |
| Einfügen, abfagen, ändern, stornieren mittels HIT-Abfragesyntax mit strukturieren Daten |
|
Weiterführende Dokumentation der APIs HitCom, HitBatch und HitRaw:
Grundsätzlich dienen die REST-Schnittstellen von HIT/ZID als Transportmittel für das
generische HIT-Protokoll.
In der Regel sind die HTTP Verben GET und POST, teilweise auch
PUT und DELETE
implementiert. Die Parameter beim GET sind im QueryString URL-encoded
anzugeben. Beim POST können die
Formulardaten mittels Content-type: application/x-www-form-urlencoded oder
application/json übermittelt werden. Die Antwortdaten werden standardmäßig im
JSON-Format ausgegeben, können aber mittels HTTP-Header Accept: application/xml auch im
XLS-Format angefordert werden.
Allgemeines zu den Endpunkten
Aus Gründen der Redundanz und Verfügbarkeit gibt es jeweils verschiedene
Server. Bei Wartungsarbeiten werden die DNS-Namen nicht-verfügbarer Server auf
andere System umgeleitet. Es ist daher kontraproduktiv, auf Client-Seite
IP-Adressen oder lang andauerndes DNS-Caching zu verwenden. Empfehlenswert ist,
bei Nichterreichbarkeit eines Servers automatisch von Seiten des Clients eine
alternative URL zu versuchen. Die verschiedenen Server sind völlig identisch ausgestattet und können in beliebiger Reihenfolge benutzt
werden.
Für die verschiedenen Systeme ("Testsystem", "Produktionssystem",
"Wartungssystem", und "Clonesystem") gibt es jeweils eine gemeinsame
URL / Webadresse unter https://www.hi-tier.de/<subweb> (www ohne angehängte Ziffer).
Hinter
der Webadresse https://www.hi-tier.de/ wird
von der DNS-Namensauflösung zufällig eine der Adressen der (derzeit) einzelnen Server
"www1", "www2", "www3" oder "www4" geliefert.
Basis-URLs der Endpunkte der verschiedenen Systeme REST v2
Testsystem
Produktionssystem
Wartungssystem
Clonesystem
Allgemein - REST Version 1 (alt)
| Die Dienste von HI-Tier sind seit September 2014 auch über einfache
Webdienste - so genannte REST-Services (Representational State Transfer) -
verfügbar. Die Kommunikation erfolgt ausschließlich über durch den Port 443.
|
| Als
Transportprotokoll muss verschlüsseltes HTTPSs verwendet werden. Die interne "Nutzlast"
basiert weiterhin auf dem HIT-Protokoll. |
| REST wurde als einfache Alternative zu ähnlichen Verfahren wie SOAP und WSDL
und dem verwandten RPC gewählt. Das Verfahren wird noch weiterentwickelt.
Insbesondere ist geplant, vereinfachte Objekt-Strukturen an zu bieten. Die jetzt
schon bestehenden Schnittstellen sind aber weitestgehend stabil. Neuerungen
sollen (möglichst) abwärtskompatibel eingeführt werden. |
Allgemeines zu den Endpunkten
Analog oben bei REST v2.
Endpunkte der verschiedenen Systeme REST v1
Testsystem
Produktionssystem
Wartungssystem
Clonesystem
Einführung in die Nutzung der Schnittstellen (API) HIT-REST v1
Grundsätzlich dienen die REST-Schnittstellen von HIT/ZID als Transportmittel für das
generische HIT-Protokoll. Es gibt die oben aufgeführten verschiedene
Schnittstellen-Gruppen mit unterschiedlicher Zielsetzung und unterschiedlicher
Nähe zum rohen HIT-Protokoll.
In der Regel sind die HTTP Verben GET und POST, teilweise auch
PUT und DELETE
implementiert. Die Parameter beim GET sind im QueryString URL-encoded
anzugeben. Beim POST können die
Formulardaten mittels Content-type: application/x-www-form-urlencoded oder
application/json übermittelt werden. Die Antwortdaten werden standardmäßig im
JSON-Format ausgegeben, können aber mittels HTTP-Header Accept: application/xml auch im
XLS-Format angefordert werden.
Weiterführende Dokumentation zu den einzelnen Schnittstellendefinitionen siehe
Data Dictionary.
Clients
Diese REST-Services können sehr einfach über verschiedene Clienttechniken
angesprochen werden.
| HitBatch Version 46 Stand 23.09.2014, kann alternativ über Port 443
mittels HTTPS kommunizieren und benötigt keine Freischaltung des
proprietären HIT-Protokolls an Port 2222 / 2223 und weiteren. |
| REST kann einfach über JavaScript aus Webseiten direkt angesprochen
werden, Beispiele finden sich direkt auf den oben angegebenen Service-URLs.
Einen sehr guten Einblick in die stattfindende Kommunikation erhält
man durch die Entwicklungs- und Debugfunktionen der Webbrowser |
|
