OBS/Kostenpflichtige Module/RESTServer/Endpunkte
- 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
Endpunkte
Ein Endpunkt definiert eine Adresse, über die der REST-Server eine konkrete Funktion anbietet. Hinter jedem Endpunkt steht entweder ein OBS-Skript (Standardfall) oder ein WebHook (Einmal-Antwort für asynchrone Rückrufe).
Aufruf
Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Endpunkte
Felder
| Feld | Beschreibung |
|---|---|
| Endpunkt | Hauptname, erster Pfad-Bestandteil nach der Hostadresse (Pflichtfeld) |
| Sub-URL | Optionaler zweiter Pfad-Bestandteil, z.B. mobile, office |
| Version | Versionsbezeichner, z.B. v1, v1.0, v2 |
| Server | Zuordnung zu einem Server-Profil. Der Endpunkt ist nur über dieses Profil erreichbar (Pflichtfeld) |
| Aktiv | Inaktive Endpunkte sind nicht ansprechbar (404) |
| Info | Freitext zur Dokumentation |
Adressbildung
Die Adresse setzt sich aus Endpunkt, Sub-URL und Version zusammen:
http://[Hostadresse][:Port]/[Endpunkt][/Sub-URL]/[Version]
Beispiele:
https://api.meinserver.de/kalender/v1 https://api.meinserver.de/email/mein_konto/v1.0
Wird die Sub-URL leer gelassen, verkürzt sich die Adresse auf /Endpunkt/Version.
Versionierung
Die Versionierung erlaubt es, eine Endpunkt-Funktionalität zu ändern, ohne bestehende Konsumenten zu brechen. Das Vorgehen:
- Den vorhandenen Endpunkt unverändert lassen, weiterhin aktiv halten.
- Einen neuen Endpunkt mit gleicher Endpunkt-/Sub-URL, aber neuer Version anlegen.
- Berechtigungen für die neuen Konsumenten setzen.
- Wenn alle Konsumenten umgestellt sind, den alten Endpunkt deaktivieren.
Zuordnung zum Server-Profil
Ein Endpunkt ist immer genau einem Server-Profil zugeordnet. Damit lassen sich z.B. der gleiche Endpunkt-Name auf einem Public-Server (Standard-TLS) und einem Internal-Server (mTLS) parallel betreiben - die jeweils dem Server zugeordneten Endpunkte werden voneinander getrennt. Ein Konsument, der über das Public-Profil zugreift, kann nicht versehentlich die mTLS-Variante ansprechen.
Berechtigungen
Damit ein Zugang einen Endpunkt aufrufen darf, muss er für diesen Endpunkt freigeschaltet sein. Aus der Endpunkt-Liste den Endpunkt markieren und F6 drücken. Es öffnet sich die Berechtigungs-Liste.
In der Berechtigungs-Liste:
- Einfg - öffnet die Zugänge-Liste.
- In der Zugänge-Liste mit F5 einen oder mehrere Zugänge markieren.
- F2 übernimmt die markierten Zugänge als Berechtigungen.
Ohne Markierung wird nur der aktuelle Zugang übernommen.
Endpunkt-Skript
Aus der Endpunkt-Liste den Endpunkt markieren und F7 drücken. Es öffnet sich der Skript-Editor. Im Skript werden GET-, POST-, PUT-, DELETE- bzw. PATCH-Funktionen implementiert, die der Server bei Aufruf der entsprechenden HTTP-Methode aufruft.
Die genaue Skript-Syntax und alle verfügbaren Parameter sind unter Scripting beschrieben.
WebHooks
Ein Endpunkt kann alternativ als WebHook konfiguriert werden. WebHooks sind Einmal-Endpunkte - sie werden in der Regel von OBS aus dynamisch für externe Dienste angelegt (z.B. Bezahl-Callbacks). Beim ersten erfolgreichen Aufruf:
- Die übergebenen Daten (Query-String oder Request-Body) werden in der Tabelle REMOTE_HOOK_URL im Feld hu_response gespeichert.
- Der Endpunkt wird automatisch aus RESTSRV_ENDPOINTS gelöscht.
- Der Server antwortet mit {"status": "ok"}.
Damit lassen sich asynchrone Rückrufe sauber konsumieren, ohne dass dauerhaft offene Endpunkte zurückbleiben. Die Anlage und Auswertung eines WebHooks erfolgt typischerweise programmgesteuert über die zugehörigen Helper-Funktionen, nicht über die Endpunkt-Maske.
Listen-Funktionen
In der Endpunkt-Liste:
- Einfg - neuer Endpunkt
- Return - Endpunkt bearbeiten
- F4 - Sortierung
- F6 - Berechtigungen verwalten (Zugänge dem Endpunkt zuordnen)
- F7 - Endpunkt-Skript bearbeiten
- F8 - Statistik für den Endpunkt
Cache
Der REST-Server cached das kompilierte Skript pro Endpunkt. Wird das Skript über F7 geändert, ist die neue Version sofort wirksam - der Server erkennt die Änderung am sys_date und compiliert neu.
Typische Fehlermeldungen
| Code | Bedeutung |
|---|---|
| 404 | Endpunkt nicht vorhanden / inaktiv / falsches Server-Profil |
| 403 | Keine Berechtigung für die Endpunkt-Nutzung (Zugang fehlt in der Berechtigungs-Liste) |
| 401 | API-Key fehlt, ungültig, JWT fehlt oder ist abgelaufen |
| 500 | Skript-Fehler oder Syntax-Fehler im Endpunkt-Skript - Detail siehe RESTSRV_PROTO |