Web Service Interface nutzen

Kommunikation

Zugriff auf API ist über HTTP oder HTTPS möglich. In einer Produktionsumgebung wird dringend die Verwendung von HTTPS empfohlen, da andernfalls primäre Zugangsdaten in Klartext übermittelt werden.

Authentifizierung

Zur Authentifizierung nutzen wir OAuth 2.0 Resource Owner Password Credentials Grant. Um Zugriff auf eine Ressource des Web Service Interface zu erhalten, benötigt der Client ein gültiges Access Token und eine gültige Session im System. Falls kein Token vorgelegt wird oder das Token ungültig ist (z. B. abgelaufen), oder die System-Session nicht zur Verfügung steht, erhält der Benutzer einen Statuscode 401 (nicht autorisiert) und muss ein Access Token anfordern. Das Access Token kann über eine dedizierte Ressource (/token) durch Vorlage der wichtigen Zugangsdaten angefordert werden. Falls die Zugangsdaten zur Verfügung gestellt werden, erstellt das System eine neue Session und sendet ein Access Token zurück.

Hinweis:
Der Client muss entweder Meldungen (z. B. Wertveränderungen) abonnieren oder muss auf die API mindestens all 10 Minuten zugreifen, da andernfalls die System-Session abläuft. Die API stellt eine dedizierte Ressource (/heartbeat) allein zu dem Zweck zur Verfügung, eine Session aktiv zu halten.

Authentifizierung des Client-Zertifikats

Ein Client kann sich optional beim Server durch Vorlage eines Client-Zertifikats authentifizieren. Die Web Service Interface erwartet, dass das Client-Zertifikat in einem Header mit der Bezeichnung X-ARR-ClientCert zur Verfügung gestellt wird. Falls der Zugriff auf die Schnittstelle über einen Reverse Proxy erfolgt (fast immer in einer Produktionsumgebung), fragt der Reverse Proxy den Client nach einem optionalen Client-Zertifikat. In diesem Fall gibt der Reverse Proxy das Client-Zertifikat als HTTP-Header an den Backend Server weiter, wobei der Standard-Header als X-ARR-ClientCert konfiguriert ist.

Subscriptions (Push-Meldungen mit SignalR)

Optional bietet die API für spezifizierte Dienste nicht nur Daten auf Anforderung (Pull), sondern auch bei einem vom entsprechenden Dienst bestimmten Ereignis (Push).

Jeder Client, der auf Push-Meldungen abonniert ist, muss SignalR unterstützen (siehe [2] [➙ 12]). Der Client muss sich zuerst mit einem dedizierten SignalR-Hub verbinden und kann dann Meldungen abonnieren, indem er eine Verbindungs-ID liefert, die er nach Herstellen der Verbindung zwischen dem Client und dem Server erhält. Der Client muss dann eine Funktion implementieren (siehe Signatur in den entsprechenden Kapiteln über die Dienstleistungen), die vom Server abgerufen werden, wenn eine Meldung fällig ist.

Latenz Push-Meldung bis Anforderung-Antwort

Im Workflow von Subscription und Meldung kann es geschehen, dass eine Push-Meldung vom Server vor der Erfolgsmeldung für die Subscription empfangen wird. Diese Latenz beruht auf der Netz-Kommunikationsverzögerung für die Meldungen an zwei unabhängigen Kanälen der SignalR-Hub-Verbindung für die Push-Meldung und die Erfolgsmeldung für die Subscription.

In derartigen Szenarien sollten die Clients eine von WSI empfangene Meldung als gültige Meldung betrachten und ihre Lösung entsprechend konzipieren.

Unterstützte Client-Umgebungen

Es bestehen keine Client-Abhängigkeiten mit Ausnahme der SignalR-Version 2.2.0 Client Bibliothek für Clients, die an Push-Meldungen interessiert sind.

Bereitstellung

Das Web Service Interface wird als selbst gehostete Komponente bereitgestellt. Sie ist ausführbar und kann wie jeder andere IOWA-Manager durch Befehle gesteuert werden.

Je nach Einsatz in einer Produktionsumgebung ist der Zugriff auf das Web Service Interface (und System) höchstwahrscheinlich nur über einen Reverse Proxy möglich.