|
| |
Allgemein - REST v2 (Version 2, neu)
 | Ab 1.April 2019 ist neue, komfortablere Version des REST-Services in Erprobung |
| Schnittstellendefinitionen, Dokumentation und Testinterface gibt es
getrennt nach Anmelde- und Datenkontext für:
|
Einführung in die Nutzung der Schnittstellen (API) HIT-REST v2
Unter den Aufrufpunkten / REST-URL der Version 2 (siehe unten) ist sowohl die
alte API v1 (Details unten) als auch die neue API v2 verfügbar.
Die neune API v2 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 im "Standard REST-Modell" |
| Einfügen, abfagen, ändern, stornieren mittels HIT-Abfragesyntax,
aber strukturieren Daten |
|
Weiterführende Dokumentation
Grundsätzlich dienen die HIT-Rest Schnittstellen als Transportmittel für das
generische HIT-Protokoll.
In der Regel sind die http Kommandos GET und POST, teilweise auch PUT und DELETE
implementiert. Die Parameter beim GET sind "URL-encoded". 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 accept: application/xml auch im
XLM-Format angefordert werden.
Weiterführende Dokumentation zu den einzelnen Schnittstellendefinitionen siehe
hier unter
Sicherheitshinweis: Auch wenn von
Allgemeines zu den Aufrufpunkten
Aus Gründen der Redundanz und Verfügbarkeit gibt es jeweils verschiedene
Server. Bei Wartungsarbeiten werden die DNS-Namen nichtverfü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 die
alternative URL zu versuchen. Der Hauptserver (primary) und der Ersatz (backup)
sind völlig identisch ausgestattet und können in beliebiger Reihenfolge benutzt
werden.
Für die verschiedenen System: "Testsystem", "Produktionssystem",
"Wartungssystem", und "Clonesystem" gibt es jeweils eine gemeinsame
URL / Webadresse unter
www.hi-tier.de/<systemadresse> (www ohne angehängte Ziffer).
Hinter
der Webadresse www.hi-tier.de wird
von der DNS-Namensauflösung zufällig die Adressen der einzelnen Server
"www1" und "www2" (bzw. synonym "www3" und "www4") geliefert.
Aufrufpunkte der verschiedenen Systeme REST v2
Testsystem
Produktionssystem
Wartungssystem
Clonesystem
Allgemein - REST v1 (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 https 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 Aufrufpunkten
Analog oben bei REST v2.
Aufrufpunkte der verschiedenen Systeme REST v1
Testsystem
Produktionssystem
Wartungssystem
Clonesystem
Einführung in die Nutzung der Schnittstellen (API) HIT-REST v1
Grundsätzlich dienen die HIT-Rest Schnittstellen 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 Kommandos GET und POST, teilweise auch PUT und DELETE
implementiert. Die Parameter beim GET sind "URL-encoded". 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 accept: application/xml auch im
XLM-Format angefordert werden.
Weiterführende Dokumentation zu den einzelnen Schnittstellendefinitionen siehe
hier unter
Clients
Diese REST-Services können sehr einfach über verschiedene Clienttechniken
angesprochen werden.
| HitBatch Version 46 Stand 23.09.2014, kann alternativ über Port 80
mittels https kommunizieren und benötigt keine Freischaltung des
proprietären HIT-Protokolls an Port 2222 / 2223. |
| 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 |
|
