OBS/Kostenpflichtige Module/RESTServer/Einrichtung
- A Preise aktualisieren
- C Personen übertragen
- E Kategorien verwalten
- G Kataloge verwalten
- I Merkliste übertragen
- K Varianten übertragen
- L Artikelvarianten übertragen
- M Referenzarten übertragen
- N Lagerbestände verwalten
- U Bestellungen einlesen
- V leere Passworte füllen
- W Update-Informationen zurücksetzen
- X Konfiguration
- Z Protokoll
Einrichtung eines REST-Endpunktes
Die folgende Reihenfolge stellt sicher, dass ein lauffaehiger Endpunkt mit moeglichst wenigen Korrektur-Schleifen entsteht.
Vorbereitung
- OBS-Support kontaktieren und das REST-Server-Modul aktivieren lassen.
- Pruefen, ob auf dem Zielrechner (OBS-Server oder dedizierter REST-Server) Port und IP-Adresse frei sind.
- Bei TLS-Profilen: TLS-Zertifikat (PEM, ggf. mit Chain), privaten Schluessel (PEM) und - falls mTLS - das CA-Root-Zertifikat bereithalten.
Schritt 1: Server-Profil anlegen
In Stammdaten -> Z Weitere Stammdaten -> REST-Server den Punkt Server oeffnen und mit Einfg ein neues Profil anlegen. Pflichtfelder:
- Nr - eindeutige Nummer (1-99), wird beim Anlegen automatisch vorgeschlagen.
- Name - sprechender Name (z.B. Public-API, Internal-mTLS, Debug-Local).
- Auswahl des Modus:
- Standard-TLS (Default): Zertifikat + Key + Root-Zertifikat hinterlegen.
- mTLS aktivieren: zusaetzlich CA-Root-Zertifikat hinterlegen, jeder Client muss ein gueltiges Cert vorlegen.
- Kein SSL aktivieren: ausschliesslich fuer lokale Tests, der Server akzeptiert dann nur Plain-HTTP.
Details siehe Server-Profile.
Schritt 2: Bindung anlegen
Im Server-Profil mit F6 die Bindungs-Liste oeffnen und mit Einfg eine neue Bindung anlegen:
- Host - IP-Adresse, auf der gelauscht werden soll (z.B. 0.0.0.0 fuer alle Adressen, 127.0.0.1 fuer lokal).
- Port - Port-Nummer (typisch 443 fuer HTTPS, 8099 fuer Debug, ggf. abweichend).
- Standard setzen, wenn diese Bindung die Standard-Bindung des Servers ist (pro Server-Profil nur eine).
Schritt 3: REST-Dienst starten / neustarten
Damit Aenderungen 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.
Schritt 4: Zugang anlegen
Unter Zugaenge mit Einfg einen neuen Zugang anlegen:
- Name - erscheint im Protokoll und in der Statistik.
- API-Key - eindeutig, mit dem Schluesselsymbol kann ein zufaelliger Key generiert werden.
- Host - optional die IP oder der Hostname des Konsumenten (sollte, wenn moeglich, immer gesetzt werden).
- Optional: CORS-Origins und JWT-Konfiguration, siehe Zugaenge.
Schritt 5: Endpunkt anlegen
Unter Endpunkte mit Einfg einen neuen Endpunkt anlegen:
- Endpunkt - der Hauptname (z.B. kalender, zeiterfa).
- Sub-URL - optional, z.B. mobile.
- Version - z.B. v1.
- Server - die Server-Auswahl bestimmt, ueber welches Server-Profil der Endpunkt erreichbar ist.
Anschliessend mit F7 das Endpunkt-Skript pflegen (siehe Scripting).
Schritt 6: Zugang fuer den Endpunkt freischalten
Aus der Endpunkt-Liste den neuen Endpunkt markieren und F6 druecken. Es oeffnet sich die Berechtigungs-Liste. Mit Einfg kann ein oder mehrere Zugaenge ausgewaehlt und mit F2 uebernommen werden. Erst nach dieser Freischaltung darf ein Zugang den Endpunkt aufrufen.
Schritt 7: Funktionspruefung
Aufruf mit einem HTTP-Client (curl, Postman, Browser-Plug-in):
curl -H "apikey: [API-KEY]" https://api.meinserver.de/[Endpunkt]/[Version]
Bei korrektem Setup erscheint die JSON-Antwort des Skripts. Fehlerfaelle werden in RESTSRV_PROTO protokolliert.
Schritt 8: Statistik und Protokoll pruefen
- In der Endpunkt-Liste F8 fuer die Statistik des Endpunkts.
- In der Zugaenge-Liste F8 fuer die Statistik des Zugangs.
- In Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Protokoll die Ereignisse pruefen.
Haeufige Stolpersteine
- Bindung angelegt, aber der Server wurde nicht neugestartet -> die Bindung ist noch nicht aktiv.
- Endpunkt einem falschen Server zugeordnet -> Aufruf liefert 404 Endpunkt nicht vorhanden oder inaktiv.
- Zugang fuer den Endpunkt nicht freigeschaltet -> Aufruf liefert 403 Keine Berechtigung fuer die Endpunkt-Nutzung.
- Falscher API-Key oder falscher Host beim Zugang -> Aufruf liefert 401 bzw. 403.
- mTLS aktiv, aber kein Client-Zertifikat installiert -> Verbindung wird waehrend des TLS-Handshakes abgebrochen.