ℹ️ Enterprise-Funktion. Verfügbar ab QuickHMI 15.

Hinweis: Version 15 ist noch nicht veröffentlicht.

Bei der Datenbereitstellung über die REST API stellt QuickHMI die freigegebenen Variablen über eine dokumentierte HTTP-Schnittstelle bereit. Fremdsysteme lesen und schreiben Werte damit ohne Zusatzprogramm: Jede Programmiersprache und jedes Werkzeug spricht HTTP, und der Zugriff funktioniert auch dort, wo Industrieprotokolle an der Firewall enden. Anders als bei den drei übrigen Wegen sendet QuickHMI nichts von sich aus, sondern antwortet auf Anfragen. Jeder Wert wird mit seiner Qualität und seinem Zeitstempel geliefert.

Abgrenzung

• Gegenüber der Datenquelle „Webservice“: Dort holt QuickHMI Daten von einem fremden HTTP-Dienst. Hier liefert QuickHMI die eigenen Variablen.
• Gegenüber der Datenbereitstellung über MQTT: Dort abonnieren Clients Topics und werden bei jeder Änderung beliefert. Hier fragt der Client, wann er etwas wissen will. Wer Änderungen zeitnah braucht, nutzt die weiter unten beschriebene Wartezeit.

Einschalten

Den Weg aktivieren Sie in den Projekt-Einstellungen im Bereich Datenbereitstellung im Reiter REST API. Welche Variablen bereitgestellt werden, legen Sie in derselben Ansicht als Regel je Datenquelle und als Ausnahme je Variable fest; das Vorgehen ist für alle Wege gleich und im Überblick beschrieben.

• Listener: eine oder mehrere Adressen in der Form schema://Adresse:Port, voreingestellt ist https://0.0.0.0:8443. 0.0.0.0 bedeutet „auf allen Netzwerkkarten“.
• Basis-Pfad: voreingestellt /api/v1. Er muss mit / beginnen und darf nur Buchstaben, Ziffern und die Zeichen / _ . - ~ enthalten.

Voreingestellt ist ausschließlich https. Über eine unverschlüsselte Verbindung wären Zugangsdaten und Werte im ersten Netzabschnitt mitlesbar. Ein Klartext-Listener ist deshalb nur zulässig, wenn kein Verfahren mit Zugangsdaten oder Client-Zertifikat aktiv ist; andernfalls verwirft ihn die Laufzeit beim Start und schreibt eine Warnung ins Protokoll. Welches TLS-Zertifikat ein Port verwendet, steuern Sie im Zertifikatsmanager.

Zugang einrichten

Die Schnittstelle kennt vier Anmeldearten, die sich kombinieren lassen. Eine erfolgreiche Anmeldung genügt.

• API-Schlüssel (Voreinstellung): der übliche Weg für Maschine zu Maschine. Der Schlüssel wird beim Erzeugen ein einziges Mal angezeigt und liegt gleichzeitig in der Zwischenablage. Im Projekt wird nur sein Fingerabdruck gespeichert, ein verlorener Schlüssel lässt sich also nicht wiederherstellen, sondern nur ersetzen. Es gibt genau einen Schlüssel; ein neuer ersetzt den vorhandenen, Clients mit dem alten kommen dann nicht mehr herein.
• Benutzeranmeldung: ein Benutzername und ein Passwort, die zur Schnittstelle gehören. Dieser Zugang hat mit den Benutzern des Projekts nichts zu tun: Ein neu angelegter Bediener bekommt dadurch keinen Zugriff auf die Schnittstelle. Das Passwort wird nicht im Klartext gespeichert und lässt sich deshalb nicht wieder anzeigen, nur neu setzen.
• Client-Zertifikat: die stärkste Stufe, siehe unten.
• Ohne Anmeldung: nur für abgeschottete Netze und nur nach ausdrücklicher Bestätigung. Diese Betriebsart schließt die übrigen aus, denn sie lässt jeden herein und macht die anderen Verfahren wirkungslos. Bei jedem Serverstart erscheint dazu eine Warnung im Protokoll.

Den Schlüssel geben Sie in der Kopfzeile X-API-Key mit, alternativ als Authorization: Bearer. Die Benutzeranmeldung erfolgt als HTTP-Basic.

curl -H "X-API-Key: <Schlüssel>" https://anlage:8443/api/v1/variables
curl -u benutzer:passwort https://anlage:8443/api/v1/variables

Nach mehreren Fehlversuchen wird die Quelladresse vorübergehend gesperrt; ab dann werden auch richtige Zugangsdaten abgewiesen. Die Grenze stellen Sie im Reiter ein, jeder Fehlversuch steht mit Adresse und Zähler im Protokoll.

Werte lesen

Alle Leseabfragen liefern dasselbe Format: Serverzeit, Gesamtzahl, Versatz und die Liste der Variablen mit Wert, Qualität, Zeitstempel, Datentyp und der Angabe, ob sie beschreibbar sind.

GET /api/v1/variables/<Datenquelle>/<Variable>   eine Variable
GET /api/v1/variables                             alle freigegebenen
GET /api/v1/variables?datasource=SPS1             eine ganze Datenquelle
GET /api/v1/variables?names=SPS1.Druck,SPS1.Temp  gezielt benannte
GET /api/v1/variables?name=Temp*                  nach Namensmuster

{"datasource":"SPS1","name":"Kesseldruck","value":3.42,"quality":"GOOD",
 "timestamp":"2026-09-04T15:38:09.612+02:00","datatype":"Real","writable":true}

Zahlen kommen als Zahlen, Wahrheitswerte als true oder false, Zeit- und Datumstypen als Text im eingestellten Anzeigeformat. Liefert eine Abfrage mehr Variablen als die eingestellte Seitengröße, blättern Sie mit offset weiter; die Gesamtzahl steht in jeder Antwort.

Für viele Namen auf einmal gibt es POST /api/v1/variables/query mit den Namen im Nachrichtenrumpf. Die Höchstzahl je Anfrage stellen Sie im Reiter ein.

Nur Änderungen, und auf Änderungen warten

Mit changedSince liefert die Schnittstelle nur die Variablen, die sich seit einem Zeitpunkt geändert haben. Zusammen mit wait hält sie die Anfrage offen, bis sich etwas ändert oder die Wartezeit abläuft. Damit sieht ein Fremdsystem Änderungen sofort, ohne im Sekundentakt zu fragen.

curl -H "X-API-Key: <Schlüssel>" "https://anlage:8443/api/v1/variables?changedSince=2026-09-04T15:00:00%2B02:00&wait=30"

Die Wartezeit wird auf die im Reiter eingestellte Obergrenze gekürzt. Läuft sie ohne Änderung ab, kommt eine leere Liste zurück, und der Aufrufer stellt die nächste Anfrage.

Werte schreiben

Ein Schreibzugriff muss zwei Schlösser passieren:

• Der Schalter „Schreibzugriff erlauben“ im Reiter. Er ist voreingestellt aus; ohne ihn beantwortet die Schnittstelle jeden Schreibversuch mit 403.
• Die Freigabe der Variablen. Nur Variablen, die für diesen Weg auf ReadWrite stehen, sind beschreibbar.

curl -H "X-API-Key: <Schlüssel>" -X PUT -H "Content-Type: application/json" -d "{\"value\":42.5}" https://anlage:8443/api/v1/variables/SPS1/Sollwert

Erfolg meldet die Schnittstelle mit 204 ohne Inhalt. 403 heißt „hier darf nicht geschrieben werden“, 422 dagegen „der Wert passt nicht“, etwa weil die Datenquelle ihn ablehnt; der Grund steht im Klartext in der Antwort.

Mehrere Werte auf einmal schreiben Sie mit POST /api/v1/variables/values. Jeder Eintrag nennt Datenquelle, Name und Wert. Die Antwort bewertet jeden Eintrag einzeln als angenommen, verboten oder unbekannt; ein abgelehnter Eintrag verwirft die übrigen nicht.

Was diese Anlage anbietet

GET /api/v1/meta liefert dieselbe Liste wie die Leseabfrage, aber ohne Werte: Name, Datenquelle, Datentyp und Freigabe. Ein Integrator sieht damit, was ihn erwartet, ohne Prozesswerte zu lesen.

Überwachung

GET /api/v1/health ist ohne Anmeldung erreichbar und liefert lediglich einen Status und die Serverzeit. Der Endpunkt ist bewusst schmal gehalten, damit ein Lastverteiler oder eine Überwachung ihn abfragen kann, ohne dass die Anlage sich dabei zu erkennen gibt. Auch HEAD wird beantwortet.

Für Entwickler

GET /api/v1/openapi.json liefert die Beschreibung der Schnittstelle im OpenAPI-Format. Sie ist ebenfalls ohne Anmeldung erreichbar, weil ein Integrator sie braucht, bevor er Zugangsdaten hat, und lässt sich in Postman oder in Codegeneratoren importieren.

Grenzen und Einstellungen

• Variablen je Antwort und Einträge je Sammelanfrage: schützen vor Antworten, die niemand mehr verarbeiten kann.
• Höchste Wartezeit für wait.
• Gleichzeitige Anfragen: die Zahl der Bearbeiter für eingehende Anfragen.
• Fehlversuche bis zur Sperre der Quelladresse.
• Erlaubte Browser-Herkünfte: nur nötig, wenn eine Webseite im Browser direkt auf die Schnittstelle zugreifen soll.

Client-Zertifikate

Ist die Anmeldeart Client-Zertifikat aktiv, weist die Schnittstelle beim ersten Verbindungsversuch ein noch unbekanntes Zertifikat ab und legt es im Zertifikatsmanager unter Abgelehnt ab, mit Herkunft, Grund und Zeitpunkt. Dort setzen Sie es auf Vertrauenswürdig, danach wird der Client angenommen. Das Zurückziehen wirkt genauso sofort.

Bei kombinierten Anmeldearten darf das Zertifikat fehlen, ein Aufrufer mit gültigem Schlüssel kommt dann trotzdem herein. Es darf aber nicht falsch sein: Wer ein Zertifikat vorlegt, dem die Anlage nicht vertraut, wird abgewiesen, auch mit gültigem Schlüssel. Die Verbindung scheitert in diesem Fall bereits beim Verbindungsaufbau.

Fehlersuche

Beim Start schreibt die Laufzeit eine Zusammenfassung ins Protokoll: die tatsächlich geöffneten Adressen, den Basis-Pfad, die aktiven Anmeldearten und die Zahl der bereitgestellten Variablen. Häufige Fälle:

• Port belegt: Der betroffene Listener startet nicht, die übrigen laufen weiter. Das Protokoll nennt den Port und schlägt vor, einen anderen zu wählen. Im Laufzeit-Register des Editors erscheint der Weg als teilweise gestartet.
• Kein Listener kommt hoch: Der Weg startet nicht. Visu und die übrigen Bereitstellungswege laufen davon unbeeinflusst weiter.
• Kein Zertifikat für den Port: Ein https-Listener ohne zugeordnetes TLS-Zertifikat startet nicht. Weisen Sie dem Port im Zertifikatsmanager eines zu oder hinterlegen Sie ein Standardzertifikat.
• Anmeldung aktiv, aber nichts hinterlegt: Fehlt der Schlüssel oder der Zugang, weist der Editor das Speichern ab. In einer von Hand bearbeiteten Projektdatei startet die Schnittstelle nicht und nennt den Grund.
• Keine Variable freigegeben: Die Schnittstelle läuft weiter und beantwortet /health und /meta, jede Abfrage liefert aber eine leere Liste. Das Protokoll weist darauf hin. So sehen Sie, dass die Schnittstelle steht, und suchen die Ursache in der Freigabe statt im Netzwerk.

Lizenz

Die Datenbereitstellung über die REST API setzt eine Enterprise-Lizenz voraus. Zugriffe über die Schnittstelle zählen nicht gegen die Zahl der Visu-Clients.