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 lauffähiger Endpunkt mit möglichst wenigen Korrektur-Schleifen entsteht.
Vorbereitung
- OBS-Support kontaktieren und das REST-Server-Modul aktivieren lassen.
- Prüfen, 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 Schlüssel (PEM) und - falls mTLS - das CA-Root-Zertifikat bereithalten.
Schritt 1: Server-Profil anlegen
In Stammdaten -> Z Weitere Stammdaten -> REST-Server den Punkt Server öffnen 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: zusätzlich CA-Root-Zertifikat hinterlegen, jeder Client muss ein gültiges Cert vorlegen.
- Kein SSL aktivieren: ausschliesslich für 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 öffnen und mit Einfg eine neue Bindung anlegen:
- 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).
- Port - Port-Nummer (typisch 443 für HTTPS, 8099 für 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 Ä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.
Schritt 4: Zugang anlegen
Unter Zugänge mit Einfg einen neuen Zugang anlegen:
- Name - erscheint im Protokoll und in der Statistik.
- API-Key - eindeutig, mit dem Schlüsselsymbol kann ein zufälliger Key generiert werden.
- Host - optional die IP oder der Hostname des Konsumenten (sollte, wenn möglich, immer gesetzt werden).
- Optional: CORS-Origins und JWT-Konfiguration, siehe Zugänge.
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, über welches Server-Profil der Endpunkt erreichbar ist.
Anschliessend mit F7 das Endpunkt-Skript pflegen (siehe Scripting).
Schritt 6: Zugang für den Endpunkt freischalten
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/[Endpunkt]/[Version]
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.
Häufige 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 für den Endpunkt nicht freigeschaltet -> Aufruf liefert 403 Keine Berechtigung für 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 während des TLS-Handshakes abgebrochen.