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, ueber die der REST-Server eine konkrete Funktion anbietet. Hinter jedem Endpunkt steht entweder ein OBS-Skript (Standardfall) oder ein WebHook (Einmal-Antwort fuer asynchrone Rueckrufe).
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 ueber 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, verkuerzt sich die Adresse auf /Endpunkt/Version.
Versionierung
Die Versionierung erlaubt es, eine Endpunkt-Funktionalitaet zu aendern, ohne bestehende Konsumenten zu brechen. Das Vorgehen:
- Den vorhandenen Endpunkt unveraendert lassen, weiterhin aktiv halten.
- Einen neuen Endpunkt mit gleicher Endpunkt-/Sub-URL, aber neuer Version anlegen.
- Berechtigungen fuer 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 ueber das Public-Profil zugreift, kann nicht versehentlich die mTLS-Variante ansprechen.
Berechtigungen
Damit ein Zugang einen Endpunkt aufrufen darf, muss er fuer diesen Endpunkt freigeschaltet sein. Aus der Endpunkt-Liste den Endpunkt markieren und F6 druecken. Es oeffnet sich die Berechtigungs-Liste.
In der Berechtigungs-Liste:
- Einfg - oeffnet die Zugaenge-Liste.
- In der Zugaenge-Liste mit F5 einen oder mehrere Zugaenge markieren.
- F2 uebernimmt die markierten Zugaenge als Berechtigungen.
Ohne Markierung wird nur der aktuelle Zugang uebernommen.
Endpunkt-Skript
Aus der Endpunkt-Liste den Endpunkt markieren und F7 druecken. Es oeffnet 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 verfuegbaren 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 fuer externe Dienste angelegt (z.B. Bezahl-Callbacks). Beim ersten erfolgreichen Aufruf:
- Die uebergebenen 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 geloescht.
- Der Server antwortet mit {"status": "ok"}.
Damit lassen sich asynchrone Rueckrufe sauber konsumieren, ohne dass dauerhaft offene Endpunkte zurueckbleiben. Die Anlage und Auswertung eines WebHooks erfolgt typischerweise programmgesteuert ueber die zugehoerigen Helper-Funktionen, nicht ueber die Endpunkt-Maske.
Listen-Funktionen
In der Endpunkt-Liste:
- Einfg - neuer Endpunkt
- Return - Endpunkt bearbeiten
- F4 - Sortierung
- F6 - Berechtigungen verwalten (Zugaenge dem Endpunkt zuordnen)
- F7 - Endpunkt-Skript bearbeiten
- F8 - Statistik fuer den Endpunkt
Cache
Der REST-Server cached das kompilierte Skript pro Endpunkt. Wird das Skript ueber F7 geaendert, ist die neue Version sofort wirksam - der Server erkennt die Aenderung am sys_date und compiliert neu.
Typische Fehlermeldungen
| Code | Bedeutung |
|---|---|
| 404 | Endpunkt nicht vorhanden / inaktiv / falsches Server-Profil |
| 403 | Keine Berechtigung fuer die Endpunkt-Nutzung (Zugang fehlt in der Berechtigungs-Liste) |
| 401 | API-Key fehlt, ungueltig, JWT fehlt oder ist abgelaufen |
| 500 | Skript-Fehler oder Syntax-Fehler im Endpunkt-Skript - Detail siehe RESTSRV_PROTO |