Zum Inhalt springen

OBS/Kostenpflichtige Module/REST-Server/Einrichtung: Unterschied zwischen den Versionen

Aus OBS Wiki
MINERVA-Rademacker (Diskussion | Beiträge)
Abschnitt Betrieb hinter einem Reverse-Proxy ergänzt [Volltext ersetzt]
MINERVA-Rademacker (Diskussion | Beiträge)
Schritte auf die neue Pflege umgestellt (Strg+2/3/4, Freischaltung per F6 in den Endpunkten, Profil am Zugang) [Volltext ersetzt]
 
(7 dazwischenliegende Versionen desselben Benutzers werden nicht angezeigt)
Zeile 1: Zeile 1:
{{Kostenpflichtige Module}}
{{Vorlage:Kostenpflichtige Module}}
{{Seitentyp|Anleitung}}
= Einrichtung =


=Einrichtung eines REST-Endpunktes=
Diese Anleitung führt Sie vom ersten Server-Profil bis zum ersten erfolgreichen Aufruf eines Endpunkts. In dieser Reihenfolge entsteht ein lauffähiger Endpunkt mit möglichst wenigen Korrekturschleifen.


Die folgende Reihenfolge stellt sicher, dass ein lauffähiger Endpunkt mit möglichst wenigen Korrektur-Schleifen entsteht.
{{Auf einen Blick|1=
* '''Server-Profil und Bindung''' legen fest, wie und wo der REST-Server erreichbar ist.
* '''Zugang''' ist der Client mit seinem API-Key, auf Wunsch mit JWT-Anmeldung.
* '''Endpunkt''' ist eine Adresse mit Skript. Erst die Freischaltung verbindet Zugang und Endpunkt.
* '''Apps''' erhalten Adresse und API-Key über den Zugangscode.
}}


==Vorbereitung==
== Voraussetzungen ==
* Das Modul REST-Server ist über den OBS-Support freigeschaltet.
* Der Datenbankabgleich ist durchgeführt. Die Tabellen <code>RESTSRV_TOKEN</code> und <code>RESTSRV_IDEMPOTENCY</code> sind vorhanden. Ohne <code>RESTSRV_TOKEN</code> stellt der Server kein JWT aus. Ohne <code>RESTSRV_IDEMPOTENCY</code> laufen schreibende Anfragen ohne Schutz vor Doppelbuchungen.
* Auf dem Rechner des REST-Dienstes (OBS-Server oder eigener Server) sind IP-Adresse und Port frei.
* Für TLS liegt eines davon bereit:
** Zertifikat (PEM, mit Zwischenzertifikat) und privater Schlüssel (PEM), bei mTLS zusätzlich das Root-Zertifikat der Client-Zertifikate,
** oder die [[OBS/Kostenpflichtige Module/REST-Server/Zertifikatserneuerung|automatische Zertifikatserneuerung]],
** oder ein [[OBS/Kostenpflichtige Module/REST-Server/Zugangscode und Zertifikats-Pin#Zertifikats-Pin|eigenes Zertifikat mit Pin]] für Apps im internen Netz.
* Wie der Server von außen erreichbar wird, ist entschieden, siehe [[OBS/Kostenpflichtige Module/REST-Server/Öffentliche Freigabe|Öffentliche Freigabe]].


# OBS-Support kontaktieren und das REST-Server-Modul aktivieren lassen.
== Vorgehen ==
# Prüfen, ob auf dem Zielrechner (OBS-Server oder dedizierter REST-Server) Port und IP-Adresse frei sind.
# Bei TLS-Profilen: TLS-Zertifikat (PEM, mit Kette), privaten Schlüssel (PEM) und - falls mTLS - das CA-Root-Zertifikat bereithalten. Alternativ nutzen Sie die automatische Zertifikatserneuerung; dann genügen ein öffentlicher Name und eine Weiterleitung von Port 80 auf diesen Server. Soll der Server nicht direkt aus dem Internet erreichbar sein, siehe [[#Betrieb hinter einem Reverse-Proxy|Betrieb hinter einem Reverse-Proxy]].


==Schritt 1: Server-Profil anlegen==
=== Server-Profil anlegen ===
{{Schritte|1=
# Wählen Sie '''Stammdaten → Z Weitere Stammdaten → REST-Server'''. Die [[OBS/Kostenpflichtige Module/REST-Server/Pflege|Pflege]] öffnet sich, links oben steht die Liste der Server-Profile.
# Drücken Sie {{Einfg}}. OBS schlägt eine freie '''Nr''' zwischen 1 und 99 vor. Tragen Sie einen '''Name''' ein, z.B. ''Public-API''.
# Hinterlegen Sie auf der Registerkarte '''3 Zertifikate''' das '''Zertifikat (cert)''' und den '''Schlüssel (key)'''. Alternativ richten Sie auf der Registerkarte '''4 Zertifikaterneuerung''' die '''Automatische Erneuerung''' oder '''Eigenes Zertifikat (Pin)''' ein.
# Für mTLS setzen Sie '''mTLS-Modus aktiv''' und hinterlegen das '''Root-Zertifikat (ca)''', gegen das die Client-Zertifikate geprüft werden.
# Setzen Sie '''kein SSL (Plain-HTTP - nur für Debug!)''' nur für lokale Tests.
# Auf der Registerkarte '''2 Rate-Limits''' passen Sie bei Bedarf die Grenzen an. ''0'' bedeutet Standard: Fenster von 60 Sekunden, 120 '''Erfolgsanfragen''' und 10 '''Fehlanfragen''' je API-Key, 600 '''Anfragen''' je Profil.
# Setzen Sie '''Aktiv''' und speichern Sie mit {{F2}}.
}}


In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server''' den Punkt '''Server''' öffnen und mit '''Einfg''' ein neues Profil anlegen. Pflichtfelder:
{{Hinweis|Das Rate-Limit zählt je API-Key, ohne Key je IP-Adresse. Alle Geräte, die denselben API-Key verwenden, teilen sich einen Zähler. Planen Sie die Grenzen nach der Zahl der Geräte je Zugang. Details: [[OBS/Kostenpflichtige Module/REST-Server/Pflege#Registerkarte: 2 Rate-Limits|Pflege]].}}


* '''Nr''' - eindeutige Nummer (1-99), wird beim Anlegen automatisch vorgeschlagen.
=== Bindung anlegen ===
* '''Name''' - sprechender Name (z.B. ''Public-API'', ''Internal-mTLS'', ''Debug-Local'').
{{Schritte|1=
* Auswahl des Modus:
# Markieren Sie in der Liste der Profile das Server-Profil und wechseln Sie mit {{Key|Strg}}+{{Key|2}} in die Liste der Bindungen.
** '''Standard-TLS''' (Default): Zertifikat und Schlüssel hinterlegen - oder auf der Registerkarte '''4 Zertifikaterneuerung''' die automatische Erneuerung aktivieren.
# Drücken Sie {{Einfg}}. Das Profil ist unter '''Server''' vorbelegt.
** '''mTLS-Modus aktiv''' setzen: zusätzlich das CA-Root-Zertifikat hinterlegen, gegen das die Client-Zertifikate geprüft werden. Jeder Client muss dann ein gültiges Zertifikat vorlegen.
# Tragen Sie unter '''Host''' die IP-Adresse ein, auf der der Dienst lauschen soll, z.B. ''0.0.0.0'' für alle Adressen.
** '''kein SSL''' setzen: ausschliesslich für lokale Tests, der Server akzeptiert dann nur Plain-HTTP.
# Tragen Sie unter '''Port''' den Port ein, z.B. ''443''.
# Setzen Sie '''Standard''' an der Bindung, deren Port im Zugangscode stehen soll. Gibt es schon eine Standard-Bindung, fragt OBS, ob der Standard wechseln soll.
# Setzen Sie '''Aktiv''' und speichern Sie mit {{F2}}.
}}


Optional lassen sich am Profil eigene '''Rate-Limit-Schwellen''' hinterlegen. Ohne
=== REST-Dienst starten ===
Angabe gelten die Standardwerte (60-Sekunden-Fenster, 120 erfolgreiche und 10
{{Schritte|1=
fehlgeschlagene Anfragen je Schlüssel, 600 Anfragen je Profil). Für Anwendungen
# Starten Sie den REST-Dienst neu. Server-Profile und Bindungen liest der Dienst nur beim Start.
ohne eigenen API-Key - typisch mobile Apps - sollten die Werte bewusst gesetzt
# Prüfen Sie im Protokoll, dass das Profil gestartet und die Bindung angelegt ist. Die Meldungen dazu nennt [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche#Typische Meldungen|Betrieb und Fehlersuche]].
werden, weil dann alle Benutzer hinter einer IP auf denselben Zähler laufen.
}}


Details siehe [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]].
=== Zugang anlegen ===
{{Schritte|1=
# Wechseln Sie mit {{Key|Strg}}+{{Key|3}} in die Liste der Zugänge und drücken Sie {{Einfg}}. Das markierte Profil ist unter '''Server''' vorbelegt. Der API-Key gilt nur auf diesem Profil.
# Tragen Sie einen '''Name''' ein. Er erscheint im Protokoll.
# Klicken Sie neben '''API-Key''' auf die Schaltfläche '''...'''. OBS erzeugt einen zufälligen Key.
# Tragen Sie unter '''Host''' die Adresse des Clients ein, wenn sie feststeht.
# Für Aufrufe aus dem Browser tragen Sie die erlaubte '''CORS-Origin''' ein, für mTLS das erwartete '''mTLS-Subject'''.
# Setzen Sie '''Aktiv''' und speichern Sie mit {{F2}}.
}}


==Schritt 2: Bindung anlegen==
Bedeutung der Felder: [[OBS/Kostenpflichtige Module/REST-Server/Pflege#Zugang|Pflege]].


Im Server-Profil mit '''F6''' die Bindungs-Liste öffnen und mit '''Einfg''' eine neue Bindung anlegen:
=== JWT-Anmeldung einrichten ===
Nur nötig, wenn sich die Benutzer einer App oder eines Portals einzeln anmelden sollen.
{{Schritte|1=
# Setzen Sie in der Eingabemaske des Zugangs den Haken '''JWT-Authentifizierung'''.
# Tragen Sie unter '''Endpunkt''' den Pfad für Anmelden, Erneuern und Abmelden ein, z.B. ''/service/auth''.
# Klicken Sie neben '''Secret-Key''' auf '''...''', um einen Schlüssel zu erzeugen.
# Tragen Sie unter '''Lebenszeit (Min)''' die Laufzeit des Access-Tokens ein. Speichern Sie mit {{F2}}.
# Drücken Sie in der Liste der Zugänge {{F7}} und schreiben Sie das Anmeldeskript mit den Methoden <code>Authenticate</code> und <code>Refresh</code>.
}}


* '''Host''' - IP-Adresse, auf der gelauscht werden soll (z.B. ''0.0.0.0'' für alle Adressen, ''127.0.0.1'' für lokal).
Aufbau des Anmeldeskripts und Ablauf beim Client: [[OBS/Kostenpflichtige Module/REST-Server/Anmeldung mit JWT|Anmeldung mit JWT]].
* '''Port''' - Port-Nummer (typisch 443 für HTTPS, 8099 für Debug, ggf. abweichend). {{Achtung|Port 8080 wird für RustDesk verwendet und darf daher nicht verwendet werden}}
* '''Standard''' setzen, wenn diese Bindung die Standard-Bindung des Servers ist (pro Server-Profil nur eine).


==Schritt 3: REST-Dienst starten / neustarten==
=== Endpunkt anlegen ===
{{Schritte|1=
# Wechseln Sie mit {{Key|Strg}}+{{Key|4}} in die Liste der Endpunkte und drücken Sie {{Einfg}}. Das markierte Profil ist unter '''Server''' vorbelegt.
# Tragen Sie das '''Pfad-Template''' ein, z.B. ''/service/auftraege'' oder ''/service/auftraege/{nr}''. Das erste Segment ist die App-Kennung im Zugangscode.
# Soll der Endpunkt Dateien annehmen, setzen Sie '''Datei-Upload''' und tragen die '''maximale Dateigröße (MB)''' ein.
# Setzen Sie '''Aktiv''' und speichern Sie mit {{F2}}.
# Drücken Sie in der Liste der Endpunkte {{F7}} und schreiben Sie das Skript. Je HTTP-Verb gibt es eine Methode: <code>Get</code>, <code>Post</code>, <code>Put</code>, <code>Patch</code>, <code>Delete</code>.
}}


Damit Änderungen an Server-Profilen oder Bindungen wirksam werden, muss der OBS REST-Server-Dienst (oder die Konsole) gestartet bzw. neugestartet werden. Das Profil wird beim Start aus der Datenbank gelesen.
Pfad-Templates und weitere Felder: [[OBS/Kostenpflichtige Module/REST-Server/Pflege#Endpunkt|Pflege]]. Aufbau der Skripte: [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]].


==Schritt 4: Zugang anlegen==
=== Zugang für den Endpunkt freischalten ===
{{Schritte|1=
# Markieren Sie in der Liste der Zugänge den Zugang.
# Wechseln Sie mit {{Key|Strg}}+{{Key|4}} in die Liste der Endpunkte. Die Spalte '''Zugriff''' zeigt mit ''X'', welche Endpunkte der Zugang schon nutzen darf.
# Drücken Sie auf dem Endpunkt {{F6}}. Für mehrere Endpunkte markieren Sie diese vorher mit {{F5}}.
}}


Unter '''Zugänge''' mit '''Einfg''' einen neuen Zugang anlegen:
Erst nach dieser Freischaltung darf ein Zugang den Endpunkt aufrufen. Details: [[OBS/Kostenpflichtige Module/REST-Server/Pflege#Zugriffskontrolle|Zugriffskontrolle]].


* '''Name''' - erscheint im Protokoll und in der Statistik.
=== Zugangscode für eine App ausgeben ===
* '''API-Key''' - eindeutig, mit dem Schlüsselsymbol kann ein zufälliger Key generiert werden.
{{Schritte|1=
* '''Host''' - optional die IP oder der Hostname des Konsumenten (sollte, wenn möglich, immer gesetzt werden).
# Wählen Sie in der Liste der Zugänge den Zugang und drücken Sie {{F6}}. Der Dialog '''Zugangscode für OBS-Smart-App''' öffnet sich mit vorbelegten Feldern.
* Optional: '''CORS-Origins''' und '''JWT-Konfiguration''', siehe [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]].
# Prüfen Sie '''Host (FQDN)''' und '''Port'''. Hier gehört die Adresse hinein, unter der das Gerät den Server erreicht.
# Drücken Sie {{F2}}, um den QR-Code anzuzeigen, oder {{F4}}, um den Code in die Zwischenablage zu kopieren.
}}


==Schritt 5: Endpunkt anlegen==
Format, Prüfregeln und Weitergabe: [[OBS/Kostenpflichtige Module/REST-Server/Zugangscode und Zertifikats-Pin|Zugangscode und Zertifikats-Pin]].


Unter '''Endpunkte''' mit '''Einfg''' einen neuen Endpunkt anlegen:
=== Funktion prüfen ===
{{Schritte|1=
# Rufen Sie den Endpunkt mit einem HTTP-Client auf, z.B. mit curl. Ein Beispiel steht unter diesen Schritten.
# Verlangt der Zugang JWT, melden Sie sich vorher am JWT-Endpunkt an und senden das Access-Token mit.
# Schreibende Aufrufe (<code>POST</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code>) brauchen zusätzlich den Header <code>Idempotency-Key</code>.
# Drücken Sie in der Liste der Endpunkte, der Zugänge oder der Profile {{F8}}, um die Statistik zu sehen.
}}


* '''Endpunkt''' - Ressourcen-/Anzeigename (z.B. ''orders'', ''kalender''); dient nur der Übersicht, nicht dem Routing.
<syntaxhighlight lang="bash">
* '''Pfad-Template''' - der maßgebliche Routing-Pfad, ggf. mit Platzhaltern (z.B. ''/orders'', ''/orders/{uid}'', ''/orders/{uid}/modules/{code}'').
curl -i -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" https://obs.example.com:8443/service/auftraege
* '''Server''' - die Server-Auswahl bestimmt, über welches Server-Profil der Endpunkt erreichbar ist.
</syntaxhighlight>
* '''Datei-Upload''' - nur setzen, wenn der Endpunkt Dateien entgegennehmen soll; dann auch die '''Max. Upload-Grösse''' in MB festlegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Beispiel6|Beispiel 6]]).


{{Hinweis|Eine Versionskennung wird als statisches Segment ins Pfad-Template aufgenommen (z.B. ''/orders/v1''); ein eigenes Versionsfeld gibt es nicht. Details: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]].}}
Alle Header und Statuscodes beschreibt [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]].


Anschliessend mit '''F7''' das Endpunkt-Skript pflegen (siehe [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]).
== Ergebnis ==
Der Aufruf liefert die Antwort des Skripts mit dem Status, den das Skript setzt, und dem Header <code>X-Trace-Id</code>. In der Statistik des Endpunkts und des Zugangs ({{F8}}) steht eine Zeile zu dem Aufruf.


==Schritt 6: Zugang für den Endpunkt freischalten==
== Wenn es nicht klappt ==
 
Der Client erhält bewusst nur eine allgemeine Meldung. Den genauen Grund finden Sie über die <code>X-Trace-Id</code> im Protokoll.
Aus der Endpunkt-Liste den neuen Endpunkt markieren und '''F6''' drücken. Es öffnet sich die Berechtigungs-Liste. Mit '''Einfg''' kann ein oder mehrere Zugänge ausgewählt und mit '''F2''' übernommen werden. Erst nach dieser Freischaltung darf ein Zugang den Endpunkt aufrufen.
 
==Schritt 7: Funktionsprüfung==
 
Aufruf mit einem HTTP-Client (curl, Postman, Browser-Plug-in):
 
curl -H "apikey: [API-KEY]" https://api.meinserver.de/[Pfad-Template]
 
Bei korrektem Setup erscheint die JSON-Antwort des Skripts. Fehlerfälle werden in '''RESTSRV_PROTO''' protokolliert.
 
==Schritt 8: Statistik und Protokoll prüfen==
 
* In der Endpunkt-Liste '''F8''' für die Statistik des Endpunkts.
* In der Zugänge-Liste '''F8''' für die Statistik des Zugangs.
* In '''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Protokoll''' die Ereignisse prüfen.
 
==Betrieb hinter einem Reverse-Proxy==
 
Läuft der REST-Server auf dem OBS-Server, soll dieser Server meist nicht direkt aus dem Internet erreichbar sein. Dann nimmt ein Reverse-Proxy die Anfragen entgegen, zum Beispiel in einer DMZ oder als Funktion der Firewall, und reicht sie an den REST-Server weiter. Von aussen ist nur der Proxy erreichbar.
 
Am Proxy und im Netz richten Sie ein:
 
* '''Öffentlicher Name:''' zeigt auf die öffentliche IP-Adresse des Proxys.
* '''Zertifikat:''' Der Proxy braucht ein öffentlich gültiges Zertifikat für diesen Namen. Die automatische Zertifikatserneuerung des REST-Servers wird nicht benötigt.
* '''Weiterleitung:''' Der Proxy leitet per HTTPS an <code>https://<OBS-Server>:<Port></code> weiter. Für diese Strecke genügt am REST-Server ein Zertifikat Ihrer internen Zertifizierungsstelle oder ein selbst signiertes, dem der Proxy vertraut.
* '''Header:''' Alle HTTP-Methoden und Header unverändert durchreichen, insbesondere ''Authorization'', ''apikey'' und ''Idempotency-Key''. Antworten nicht zwischenspeichern. Den Header ''X-Forwarded-For'' mit der IP-Adresse des Konsumenten setzen.
* '''Anfragegrösse:''' Die maximale Anfragegrösse am Proxy darf nicht unter der Upload-Grenze der Endpunkte liegen.
* '''Firewall:''' Den Port des REST-Servers intern nur für den Proxy freigeben.
 
Hinter dem Proxy verhält sich der REST-Server so:
 
* Protokoll und Konsole zeigen als Host die IP-Adresse des Proxys und hängen den Wert von ''X-Forwarded-For'' als <code>[xff=…]</code> an.
* Die [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge#Host-Beschränkung|Host-Beschränkung]] eines Zugangs kann keine einzelnen Konsumenten unterscheiden.
* Beim [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile#Rate-Limit je Profil|Rate-Limit]] teilen sich alle Konsumenten ohne API-Key einen Zähler.
 
==Wartung der Server-Tabellen==
 
Die Tabellen des REST-Servers pflegen sich selbst; ein regelmässiger Eingriff ist
nicht vorgesehen:


{| class="wikitable"
{| class="wikitable"
! Tabelle !! Aufräumen
! Meldung !! Ursache
|-
| Neue Bindung antwortet nicht || Der REST-Dienst wurde nach dem Anlegen nicht neu gestartet.
|-
| Protokoll: „Fehler: Server [&lt;Profil&gt;]: SSL/TLS-Konfiguration fehlt (rsv_cert/rsv_key) - Server kann nicht starten“ || '''Zertifikat (cert)''' oder '''Schlüssel (key)''' fehlt. Nur dieses Profil startet nicht.
|-
| Verbindung bricht ab oder 400 „Ungültige Anfragezeile.“ || Der Client verwendet <code>https://</code>, das Profil läuft mit '''kein SSL (Plain-HTTP - nur für Debug!)'''.
|-
| 400 „Dieser Port erwartet eine TLS-Verbindung. Die Anfrage wurde im Klartext gesendet - bitte https verwenden.“ || Der Client verwendet <code>http://</code> auf einem Profil mit TLS.
|-
| Verbindung bricht beim TLS-Aufbau ab || '''mTLS-Modus aktiv''' ist gesetzt, der Client legt kein gültiges Client-Zertifikat vor.
|-
| 401 <code>API_KEY_INVALID</code> || Der API-Key ist unbekannt oder gehört zu einem Zugang eines anderen Server-Profils. Ohne Header <code>apikey</code>: Es gibt keinen Zugang mit dem API-Key <code>*</code>.
|-
| 401 <code>AUTH_REQUIRED</code> || Am Zugang ist '''JWT-Authentifizierung''' gesetzt, der Client sendet kein Access-Token.
|-
| 403 <code>FORBIDDEN_ROLE</code> „Zugriff verweigert“ || Zugang nicht '''Aktiv''', Anfrage nicht vom eingetragenen '''Host''', '''CORS-Origin''' nicht erlaubt oder der Zugang ist nicht für den Endpunkt freigeschaltet. Im letzten Fall steht im Protokoll „Keine Berechtigung für die Endpunkt-Nutzung“.
|-
| 404 <code>NOT_FOUND</code> || Kein '''Pfad-Template''' passt, die Zahl der Segmente stimmt nicht, der Endpunkt ist nicht '''Aktiv''' oder einem anderen '''Server''' zugeordnet. Im Protokoll steht „Endpunkt nicht vorhanden oder inaktiv“.
|-
| 400 <code>IDEMPOTENCY_KEY_MISSING</code> || Ein schreibender Aufruf ohne Header <code>Idempotency-Key</code>.
|-
|-
| RESTSRV_IDEMPOTENCY || Abgeschlossene Einträge werden nach 30 Tagen gelöscht. Offene Reservierungen werden ab 24 Stunden im Protokoll gemeldet und '''anschliessend ebenfalls gelöscht''' - sie sind trotzdem ein Support-Fall, weil die Fachwirkung unbekannt ist, siehe Stolpersteine
| 415 <code>UNSUPPORTED_MEDIA_TYPE</code> bei einem Upload || '''Datei-Upload''' ist am Endpunkt nicht gesetzt.
|-
|-
| RESTSRV_TOKEN || Zeilen werden gelöscht, sobald Access- '''und''' Refresh-Laufzeit vorbei sind. Läuft beim Serverstart und danach höchstens stündlich
| 503 bei der Anmeldung am JWT-Endpunkt || Die Tabelle <code>RESTSRV_TOKEN</code> fehlt oder ist nicht beschreibbar. Datenbankabgleich durchführen.
|-
|-
| RESTSRV_PROTO / RESTSRV_STATS || Wachsen mit dem Betrieb. Bei hohem Aufkommen empfiehlt sich ein turnusmässiges Archivieren
| Änderung an Endpunkt oder Skript wirkt nicht || Der Server hält Endpunkte bis zu 60 Sekunden im Speicher. Kurz warten.
|}
|}


==Häufige Stolpersteine==
Weitere Fehlerbilder, Proxy-Betrieb und Wartung der Tabellen: [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]].


* Bindung angelegt, aber der Server wurde nicht neugestartet -> die Bindung ist noch nicht aktiv.
== Siehe auch ==
* Endpunkt einem falschen Server zugeordnet -> Aufruf liefert 404 ''Endpunkt nicht vorhanden oder inaktiv''.
* [[OBS/Kostenpflichtige Module/REST-Server|REST-Server]]
* Pfad-Template falsch geschrieben oder Segmentzahl passt nicht -> kein Template matcht, Aufruf liefert 404.
* [[OBS/Kostenpflichtige Module/REST-Server/Öffentliche Freigabe|Öffentliche Freigabe]]
* Zugang für den Endpunkt nicht freigeschaltet -> Aufruf liefert 403 ''Keine Berechtigung für die Endpunkt-Nutzung''.
* [[OBS/Kostenpflichtige Module/REST-Server/Pflege|Pflege]]
* Falscher API-Key oder falscher Host beim Zugang -> Aufruf liefert 401 bzw. 403.
* [[OBS/Kostenpflichtige Module/REST-Server/Betrieb und Fehlersuche|Betrieb und Fehlersuche]]
* mTLS aktiv, aber kein Client-Zertifikat installiert -> Verbindung wird während des TLS-Handshakes abgebrochen.
* Datei-Upload ohne gesetzten Haken '''Datei-Upload''' am Endpunkt -> Aufruf liefert 415, das Skript läuft nicht an.
* Skript geändert, aber der Aufruf verhält sich noch wie vorher -> Endpunkt-Cache abwarten (bis zu 60 Sekunden).
* Schreibaufruf (POST/PUT/PATCH/DELETE) liefert 400 ''IDEMPOTENCY_KEY_MISSING'' -> der Client sendet keinen ''Idempotency-Key''. Der Header ist seit v1.21 '''Pflicht''', nicht optional; das Endpunkt-Skript läuft in diesem Fall gar nicht an. Betrifft typischerweise Konsumenten, die vor dem Update gebaut wurden.
* Wiederholter Schreibaufruf liefert 422 ''IDEMPOTENCY_KEY_REUSED'' -> der Client sendet denselben ''Idempotency-Key'' mit geändertem Inhalt. Pro Vorgang genau ein Schlüssel, über alle Wiederholversuche hinweg unverändert.
* Wiederholter Schreibaufruf liefert 409 ''IDEMPOTENCY_UNRESOLVED'' -> ein früherer Versuch wurde hart abgebrochen (Dienst beendet). Ob gebucht wurde, ist offen: im Protokoll und in den Fachdaten prüfen. Der Aufräumlauf meldet den Eintrag nach 24 Stunden im Protokoll und löscht ihn dann; wer schneller weitermachen will, entfernt ihn in '''RESTSRV_IDEMPOTENCY'''.
* Nach einem Update antworten '''alle''' bestehenden Token mit 401 ''AUTH_EXPIRED'' -> erwartetes Verhalten. Token, die vor der Einführung der Sitzungsprüfung ausgestellt wurden, gehören zu keiner Sitzung; die Konsumenten müssen sich einmalig neu anmelden.
* Anmeldung liefert 503 statt eines Tokens -> die Sitzungszeile konnte nicht geschrieben werden. Ursache im Protokoll unter ''TokenStore: ...'' nachsehen; typisch ist eine fehlende Tabelle '''RESTSRV_TOKEN''' nach einem Update ohne Datenbank-Abgleich.
* Abmelden liefert 503 -> die Sitzung liess sich nicht sperren. Der Client ist '''nicht''' abgemeldet und muss den Aufruf wiederholen; Details im Protokoll.
* Techniker wird beim Arbeiten unerwartet abgemeldet -> im Protokoll nach ''WIEDERVORLAGE'' suchen. Ein doppelt verwendetes Refresh-Token sperrt die Sitzung. Legt die App Token mehrfach parallel ab, gehört das clientseitig behoben.

Aktuelle Version vom 17. November 2026, 11:53 Uhr

Einrichtung

Diese Anleitung führt Sie vom ersten Server-Profil bis zum ersten erfolgreichen Aufruf eines Endpunkts. In dieser Reihenfolge entsteht ein lauffähiger Endpunkt mit möglichst wenigen Korrekturschleifen.

Auf einen Blick
  • Server-Profil und Bindung legen fest, wie und wo der REST-Server erreichbar ist.
  • Zugang ist der Client mit seinem API-Key, auf Wunsch mit JWT-Anmeldung.
  • Endpunkt ist eine Adresse mit Skript. Erst die Freischaltung verbindet Zugang und Endpunkt.
  • Apps erhalten Adresse und API-Key über den Zugangscode.

Voraussetzungen

  • Das Modul REST-Server ist über den OBS-Support freigeschaltet.
  • Der Datenbankabgleich ist durchgeführt. Die Tabellen RESTSRV_TOKEN und RESTSRV_IDEMPOTENCY sind vorhanden. Ohne RESTSRV_TOKEN stellt der Server kein JWT aus. Ohne RESTSRV_IDEMPOTENCY laufen schreibende Anfragen ohne Schutz vor Doppelbuchungen.
  • Auf dem Rechner des REST-Dienstes (OBS-Server oder eigener Server) sind IP-Adresse und Port frei.
  • Für TLS liegt eines davon bereit:
  • Wie der Server von außen erreichbar wird, ist entschieden, siehe Öffentliche Freigabe.

Vorgehen

Server-Profil anlegen

  1. Wählen Sie Stammdaten → Z Weitere Stammdaten → REST-Server. Die Pflege öffnet sich, links oben steht die Liste der Server-Profile.
  2. Drücken Sie Einfg. OBS schlägt eine freie Nr zwischen 1 und 99 vor. Tragen Sie einen Name ein, z.B. Public-API.
  3. Hinterlegen Sie auf der Registerkarte 3 Zertifikate das Zertifikat (cert) und den Schlüssel (key). Alternativ richten Sie auf der Registerkarte 4 Zertifikaterneuerung die Automatische Erneuerung oder Eigenes Zertifikat (Pin) ein.
  4. Für mTLS setzen Sie mTLS-Modus aktiv und hinterlegen das Root-Zertifikat (ca), gegen das die Client-Zertifikate geprüft werden.
  5. Setzen Sie kein SSL (Plain-HTTP - nur für Debug!) nur für lokale Tests.
  6. Auf der Registerkarte 2 Rate-Limits passen Sie bei Bedarf die Grenzen an. 0 bedeutet Standard: Fenster von 60 Sekunden, 120 Erfolgsanfragen und 10 Fehlanfragen je API-Key, 600 Anfragen je Profil.
  7. Setzen Sie Aktiv und speichern Sie mit F2.
HINWEIS: Das Rate-Limit zählt je API-Key, ohne Key je IP-Adresse. Alle Geräte, die denselben API-Key verwenden, teilen sich einen Zähler. Planen Sie die Grenzen nach der Zahl der Geräte je Zugang. Details: Pflege.

Bindung anlegen

  1. Markieren Sie in der Liste der Profile das Server-Profil und wechseln Sie mit Strg+2 in die Liste der Bindungen.
  2. Drücken Sie Einfg. Das Profil ist unter Server vorbelegt.
  3. Tragen Sie unter Host die IP-Adresse ein, auf der der Dienst lauschen soll, z.B. 0.0.0.0 für alle Adressen.
  4. Tragen Sie unter Port den Port ein, z.B. 443.
  5. Setzen Sie Standard an der Bindung, deren Port im Zugangscode stehen soll. Gibt es schon eine Standard-Bindung, fragt OBS, ob der Standard wechseln soll.
  6. Setzen Sie Aktiv und speichern Sie mit F2.

REST-Dienst starten

  1. Starten Sie den REST-Dienst neu. Server-Profile und Bindungen liest der Dienst nur beim Start.
  2. Prüfen Sie im Protokoll, dass das Profil gestartet und die Bindung angelegt ist. Die Meldungen dazu nennt Betrieb und Fehlersuche.

Zugang anlegen

  1. Wechseln Sie mit Strg+3 in die Liste der Zugänge und drücken Sie Einfg. Das markierte Profil ist unter Server vorbelegt. Der API-Key gilt nur auf diesem Profil.
  2. Tragen Sie einen Name ein. Er erscheint im Protokoll.
  3. Klicken Sie neben API-Key auf die Schaltfläche .... OBS erzeugt einen zufälligen Key.
  4. Tragen Sie unter Host die Adresse des Clients ein, wenn sie feststeht.
  5. Für Aufrufe aus dem Browser tragen Sie die erlaubte CORS-Origin ein, für mTLS das erwartete mTLS-Subject.
  6. Setzen Sie Aktiv und speichern Sie mit F2.

Bedeutung der Felder: Pflege.

JWT-Anmeldung einrichten

Nur nötig, wenn sich die Benutzer einer App oder eines Portals einzeln anmelden sollen.

  1. Setzen Sie in der Eingabemaske des Zugangs den Haken JWT-Authentifizierung.
  2. Tragen Sie unter Endpunkt den Pfad für Anmelden, Erneuern und Abmelden ein, z.B. /service/auth.
  3. Klicken Sie neben Secret-Key auf ..., um einen Schlüssel zu erzeugen.
  4. Tragen Sie unter Lebenszeit (Min) die Laufzeit des Access-Tokens ein. Speichern Sie mit F2.
  5. Drücken Sie in der Liste der Zugänge F7 und schreiben Sie das Anmeldeskript mit den Methoden Authenticate und Refresh.

Aufbau des Anmeldeskripts und Ablauf beim Client: Anmeldung mit JWT.

Endpunkt anlegen

  1. Wechseln Sie mit Strg+4 in die Liste der Endpunkte und drücken Sie Einfg. Das markierte Profil ist unter Server vorbelegt.
  2. Tragen Sie das Pfad-Template ein, z.B. /service/auftraege oder /service/auftraege/{nr}. Das erste Segment ist die App-Kennung im Zugangscode.
  3. Soll der Endpunkt Dateien annehmen, setzen Sie Datei-Upload und tragen die maximale Dateigröße (MB) ein.
  4. Setzen Sie Aktiv und speichern Sie mit F2.
  5. Drücken Sie in der Liste der Endpunkte F7 und schreiben Sie das Skript. Je HTTP-Verb gibt es eine Methode: Get, Post, Put, Patch, Delete.

Pfad-Templates und weitere Felder: Pflege. Aufbau der Skripte: Scripting.

Zugang für den Endpunkt freischalten

  1. Markieren Sie in der Liste der Zugänge den Zugang.
  2. Wechseln Sie mit Strg+4 in die Liste der Endpunkte. Die Spalte Zugriff zeigt mit X, welche Endpunkte der Zugang schon nutzen darf.
  3. Drücken Sie auf dem Endpunkt F6. Für mehrere Endpunkte markieren Sie diese vorher mit F5.

Erst nach dieser Freischaltung darf ein Zugang den Endpunkt aufrufen. Details: Zugriffskontrolle.

Zugangscode für eine App ausgeben

  1. Wählen Sie in der Liste der Zugänge den Zugang und drücken Sie F6. Der Dialog Zugangscode für OBS-Smart-App öffnet sich mit vorbelegten Feldern.
  2. Prüfen Sie Host (FQDN) und Port. Hier gehört die Adresse hinein, unter der das Gerät den Server erreicht.
  3. Drücken Sie F2, um den QR-Code anzuzeigen, oder F4, um den Code in die Zwischenablage zu kopieren.

Format, Prüfregeln und Weitergabe: Zugangscode und Zertifikats-Pin.

Funktion prüfen

  1. Rufen Sie den Endpunkt mit einem HTTP-Client auf, z.B. mit curl. Ein Beispiel steht unter diesen Schritten.
  2. Verlangt der Zugang JWT, melden Sie sich vorher am JWT-Endpunkt an und senden das Access-Token mit.
  3. Schreibende Aufrufe (POST, PUT, PATCH, DELETE) brauchen zusätzlich den Header Idempotency-Key.
  4. Drücken Sie in der Liste der Endpunkte, der Zugänge oder der Profile F8, um die Statistik zu sehen.
curl -i -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" https://obs.example.com:8443/service/auftraege

Alle Header und Statuscodes beschreibt HTTP-Schnittstelle.

Ergebnis

Der Aufruf liefert die Antwort des Skripts mit dem Status, den das Skript setzt, und dem Header X-Trace-Id. In der Statistik des Endpunkts und des Zugangs (F8) steht eine Zeile zu dem Aufruf.

Wenn es nicht klappt

Der Client erhält bewusst nur eine allgemeine Meldung. Den genauen Grund finden Sie über die X-Trace-Id im Protokoll.

Meldung Ursache
Neue Bindung antwortet nicht Der REST-Dienst wurde nach dem Anlegen nicht neu gestartet.
Protokoll: „Fehler: Server [<Profil>]: SSL/TLS-Konfiguration fehlt (rsv_cert/rsv_key) - Server kann nicht starten“ Zertifikat (cert) oder Schlüssel (key) fehlt. Nur dieses Profil startet nicht.
Verbindung bricht ab oder 400 „Ungültige Anfragezeile.“ Der Client verwendet https://, das Profil läuft mit kein SSL (Plain-HTTP - nur für Debug!).
400 „Dieser Port erwartet eine TLS-Verbindung. Die Anfrage wurde im Klartext gesendet - bitte https verwenden.“ Der Client verwendet http:// auf einem Profil mit TLS.
Verbindung bricht beim TLS-Aufbau ab mTLS-Modus aktiv ist gesetzt, der Client legt kein gültiges Client-Zertifikat vor.
401 API_KEY_INVALID Der API-Key ist unbekannt oder gehört zu einem Zugang eines anderen Server-Profils. Ohne Header apikey: Es gibt keinen Zugang mit dem API-Key *.
401 AUTH_REQUIRED Am Zugang ist JWT-Authentifizierung gesetzt, der Client sendet kein Access-Token.
403 FORBIDDEN_ROLE „Zugriff verweigert“ Zugang nicht Aktiv, Anfrage nicht vom eingetragenen Host, CORS-Origin nicht erlaubt oder der Zugang ist nicht für den Endpunkt freigeschaltet. Im letzten Fall steht im Protokoll „Keine Berechtigung für die Endpunkt-Nutzung“.
404 NOT_FOUND Kein Pfad-Template passt, die Zahl der Segmente stimmt nicht, der Endpunkt ist nicht Aktiv oder einem anderen Server zugeordnet. Im Protokoll steht „Endpunkt nicht vorhanden oder inaktiv“.
400 IDEMPOTENCY_KEY_MISSING Ein schreibender Aufruf ohne Header Idempotency-Key.
415 UNSUPPORTED_MEDIA_TYPE bei einem Upload Datei-Upload ist am Endpunkt nicht gesetzt.
503 bei der Anmeldung am JWT-Endpunkt Die Tabelle RESTSRV_TOKEN fehlt oder ist nicht beschreibbar. Datenbankabgleich durchführen.
Änderung an Endpunkt oder Skript wirkt nicht Der Server hält Endpunkte bis zu 60 Sekunden im Speicher. Kurz warten.

Weitere Fehlerbilder, Proxy-Betrieb und Wartung der Tabellen: Betrieb und Fehlersuche.

Siehe auch