OBS/Kostenpflichtige Module/REST-Server/Einrichtung: Unterschied zwischen den Versionen
Navigationsvorlage mit Vorlage:-Praefix [Volltext ersetzt] [Styleguide-Abweichung: Seitenkopf der Altseite] |
Als Anleitung neu gegliedert, JWT, Zugangscode und Datenbankabgleich ergänzt, Tasten und Fehlermeldungen nach Masken und Code korrigiert, Proxy/Wartung verlinkt [Volltext ersetzt] |
||
| Zeile 1: | Zeile 1: | ||
{{Vorlage:Kostenpflichtige Module}} | {{Vorlage:Kostenpflichtige Module}} | ||
{{Seitentyp|Anleitung}} | |||
= 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|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. | |||
}} | |||
== | == 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/RESTServer/Zertifikatserneuerung|automatische Zertifikatserneuerung]], | |||
** oder ein [[OBS/Kostenpflichtige Module/RESTServer/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/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]]. | |||
== Vorgehen == | |||
== | === Server-Profil anlegen === | ||
{{Schritte|1= | |||
# Wählen Sie '''Stammdaten → Z Weitere Stammdaten → REST-Server''' und öffnen Sie den Punkt '''Server'''. | |||
# 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}}. | |||
}} | |||
{{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/RESTServer/Server-Profile|Server-Profile]].}} | |||
=== Bindung anlegen === | |||
{{Schritte|1= | |||
# Wählen Sie in der Liste das Server-Profil und drücken Sie {{F6}}. Die Liste der Bindungen öffnet sich. | |||
# Drücken Sie {{Einfg}}. | |||
# Tragen Sie unter '''Host''' die IP-Adresse ein, auf der der Dienst lauschen soll, z.B. ''0.0.0.0'' für alle Adressen. | |||
# Tragen Sie unter '''Port''' den Port ein, z.B. ''443''. | |||
# Setzen Sie '''Standard''' an der Bindung, deren Port im Zugangscode stehen soll. | |||
# Setzen Sie '''Aktiv''' und speichern Sie mit {{F2}}. | |||
}} | |||
=== REST-Dienst starten === | |||
{{Schritte|1= | |||
# Starten Sie den REST-Dienst neu. Server-Profile und Bindungen liest der Dienst nur beim Start. | |||
# Prüfen Sie im Protokoll, dass das Profil gestartet und die Bindung angelegt ist. Die Meldungen dazu nennt [[OBS/Kostenpflichtige Module/RESTServer/Betrieb und Fehlersuche#Typische Meldungen|Betrieb und Fehlersuche]]. | |||
}} | |||
=== Zugang anlegen === | |||
{{Schritte|1= | |||
# Öffnen Sie unter '''REST-Server''' den Punkt '''Zugänge''' und drücken Sie {{Einfg}}. | |||
# 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}}. | |||
}} | |||
Bedeutung der Felder: [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]]. | |||
=== 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>. | |||
}} | |||
Aufbau des Anmeldeskripts und Ablauf beim Client: [[OBS/Kostenpflichtige Module/RESTServer/Anmeldung mit JWT|Anmeldung mit JWT]]. | |||
== | === Endpunkt anlegen === | ||
{{Schritte|1= | |||
# Öffnen Sie unter '''REST-Server''' den Punkt '''Endpunkte''' und drücken Sie {{Einfg}}. | |||
# Tragen Sie das '''Pfad-Template''' ein, z.B. ''/service/auftraege'' oder ''/service/auftraege/{nr}''. Das erste Segment ist die App-Kennung im Zugangscode. | |||
# Wählen Sie unter '''Server''' das Server-Profil, über das der Endpunkt erreichbar ist. | |||
# 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>. | |||
}} | |||
Pfad-Templates und weitere Felder: [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]]. Aufbau der Skripte: [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]]. | |||
== | === Zugang für den Endpunkt freischalten === | ||
{{Schritte|1= | |||
# Wählen Sie in der Liste der Endpunkte den Endpunkt und drücken Sie {{F6}}. Die Liste '''Endpunkt Zugang''' öffnet sich. | |||
# Drücken Sie {{Einfg}}. Die Liste der Zugänge öffnet sich zur Auswahl. | |||
# Markieren Sie mit {{F5}} einen oder mehrere Zugänge. | |||
# Drücken Sie {{F2}}. OBS übernimmt die markierten Zugänge. Ohne Markierung übernimmt {{F2}} den Zugang, auf dem der Cursor steht. | |||
}} | |||
Erst nach dieser Freischaltung darf ein Zugang den Endpunkt aufrufen. | |||
=== Zugangscode für eine App ausgeben === | |||
{{Schritte|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. | |||
# 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. | |||
}} | |||
Format, Prüfregeln und Weitergabe: [[OBS/Kostenpflichtige Module/RESTServer/Zugangscode und Zertifikats-Pin|Zugangscode und Zertifikats-Pin]]. | |||
=== 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 oder der Zugänge {{F8}}, um die Statistik zu sehen. | |||
}} | |||
<syntaxhighlight lang="bash"> | |||
curl -i -H "apikey: abcdef-ghij-klmn-opqr-stuvwx" https://obs.example.com:8443/service/auftraege | |||
</syntaxhighlight> | |||
Alle Header und Statuscodes beschreibt [[OBS/Kostenpflichtige Module/RESTServer/HTTP-Schnittstelle|HTTP-Schnittstelle]]. | |||
== 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. | |||
== | == 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. | |||
{| class="wikitable" | {| class="wikitable" | ||
! | ! 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 „Ungueltige 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. 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 fuer 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>. | |||
|- | |- | ||
| | | 415 <code>UNSUPPORTED_MEDIA_TYPE</code> bei einem Upload || '''Datei-Upload''' ist am Endpunkt nicht gesetzt. | ||
|- | |- | ||
| | | 503 bei der Anmeldung am JWT-Endpunkt || Die Tabelle <code>RESTSRV_TOKEN</code> 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: [[OBS/Kostenpflichtige Module/RESTServer/Betrieb und Fehlersuche|Betrieb und Fehlersuche]]. | |||
* | == Siehe auch == | ||
* [[OBS/Kostenpflichtige Module/RESTServer|REST-Server]] | |||
* | * [[OBS/Kostenpflichtige Module/RESTServer/Öffentliche Freigabe|Öffentliche Freigabe]] | ||
* | * [[OBS/Kostenpflichtige Module/RESTServer/Server-Profile|Server-Profile]] | ||
* | * [[OBS/Kostenpflichtige Module/RESTServer/Zugaenge|Zugänge]] | ||
* | * [[OBS/Kostenpflichtige Module/RESTServer/Endpunkte|Endpunkte]] | ||
* [[OBS/Kostenpflichtige Module/RESTServer/Betrieb und Fehlersuche|Betrieb und Fehlersuche]] | |||
* | |||
Version vom 17. November 2026, 06:59 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.
- 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_TOKENundRESTSRV_IDEMPOTENCYsind vorhanden. OhneRESTSRV_TOKENstellt der Server kein JWT aus. OhneRESTSRV_IDEMPOTENCYlaufen 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 automatische Zertifikatserneuerung,
- oder ein eigenes Zertifikat mit Pin für Apps im internen Netz.
- Wie der Server von außen erreichbar wird, ist entschieden, siehe Öffentliche Freigabe.
Vorgehen
Server-Profil anlegen
- Wählen Sie Stammdaten → Z Weitere Stammdaten → REST-Server und öffnen Sie den Punkt Server.
- 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.
Bindung anlegen
- Wählen Sie in der Liste das Server-Profil und drücken Sie F6. Die Liste der Bindungen öffnet sich.
- Drücken Sie Einfg.
- Tragen Sie unter Host die IP-Adresse ein, auf der der Dienst lauschen soll, z.B. 0.0.0.0 für alle Adressen.
- Tragen Sie unter Port den Port ein, z.B. 443.
- Setzen Sie Standard an der Bindung, deren Port im Zugangscode stehen soll.
- Setzen Sie Aktiv und speichern Sie mit F2.
REST-Dienst starten
- Starten Sie den REST-Dienst neu. Server-Profile und Bindungen liest der Dienst nur beim Start.
- Prüfen Sie im Protokoll, dass das Profil gestartet und die Bindung angelegt ist. Die Meldungen dazu nennt Betrieb und Fehlersuche.
Zugang anlegen
- Öffnen Sie unter REST-Server den Punkt Zugänge und drücken Sie Einfg.
- 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.
Bedeutung der Felder: Zugänge.
JWT-Anmeldung einrichten
Nur nötig, wenn sich die Benutzer einer App oder eines Portals einzeln anmelden sollen.
- 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
AuthenticateundRefresh.
Aufbau des Anmeldeskripts und Ablauf beim Client: Anmeldung mit JWT.
Endpunkt anlegen
- Öffnen Sie unter REST-Server den Punkt Endpunkte und drücken Sie Einfg.
- Tragen Sie das Pfad-Template ein, z.B. /service/auftraege oder /service/auftraege/{nr}. Das erste Segment ist die App-Kennung im Zugangscode.
- Wählen Sie unter Server das Server-Profil, über das der Endpunkt erreichbar ist.
- 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:
Get,Post,Put,Patch,Delete.
Pfad-Templates und weitere Felder: Endpunkte. Aufbau der Skripte: Scripting.
Zugang für den Endpunkt freischalten
- Wählen Sie in der Liste der Endpunkte den Endpunkt und drücken Sie F6. Die Liste Endpunkt Zugang öffnet sich.
- Drücken Sie Einfg. Die Liste der Zugänge öffnet sich zur Auswahl.
- Markieren Sie mit F5 einen oder mehrere Zugänge.
- Drücken Sie F2. OBS übernimmt die markierten Zugänge. Ohne Markierung übernimmt F2 den Zugang, auf dem der Cursor steht.
Erst nach dieser Freischaltung darf ein Zugang den Endpunkt aufrufen.
Zugangscode für eine App ausgeben
- 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.
- 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.
Format, Prüfregeln und Weitergabe: Zugangscode und Zertifikats-Pin.
Funktion prüfen
- 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 (
POST,PUT,PATCH,DELETE) brauchen zusätzlich den HeaderIdempotency-Key. - Drücken Sie in der Liste der Endpunkte oder der Zugänge 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 „Ungueltige 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. 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 fuer 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.