OBS/Kostenpflichtige Module/REST-Server/Endpunkte
Endpunkte
Ein Endpunkt stellt eine Adresse bereit, über die der REST-Server eine Funktion anbietet. Hinter jedem Endpunkt steht ein OBS-Skript oder ein WebHook. So veröffentlichen Sie genau die Daten und Vorgänge, die eine Anwendung braucht, und vergeben die Rechte je Adresse. Sie erreichen die Endpunkte über Stammdaten → Z Weitere Stammdaten → REST-Server → Endpunkte.
Liste
Die Liste zeigt alle Endpunkte mit Pfad (dem Pfad-Template) und Serv (der Nummer des Server-Profils). Aktive Endpunkte erscheinen fett.
Tasten und Schaltflächen
| Taste | Funktion |
|---|---|
| Einfg | Legt einen neuen Endpunkt an. |
| ↩ Enter | Öffnet den markierten Endpunkt in der Eingabemaske. |
| F4 | Wählt die Sortierung. |
| F6 | Schaltfläche F6 Zugang: öffnet die Liste der Zugänge, die diesen Endpunkt nutzen dürfen, siehe Zugriffskontrolle. |
| F7 | Schaltfläche F7 Script: öffnet das Skript des Endpunkts im Skript-Editor. Wie Sie es schreiben, beschreibt Scripting. |
| F8 | Schaltfläche F8 Stat: zeigt die Statistik der Anfragen an diesen Endpunkt. |
Eingabemaske
↩ Enter öffnet die Eingabemaske REST-Endpunkt. Ein neuer Endpunkt ist als Aktiv vorbelegt.
| Feld | Bedeutung |
|---|---|
| Pfad-Template | Vollständiger Pfad nach Host und Port, mit Platzhaltern, z.B. /orders/{uid}/modules/{code}. Maßgeblich für die Zuordnung der Anfragen, siehe Routing über Pfad-Templates. Pflichtfeld.
|
| Server | Server-Profil, auf dem der Endpunkt erreichbar ist. Auf anderen Profilen antwortet der Server für diesen Pfad mit 404. Pflichtfeld. |
| zusätzliche Infos | Freitext zur Dokumentation. Wird nicht ausgewertet. |
| Datei-Upload | Der Endpunkt nimmt Dateien an. Ohne Haken weist der Server Uploads mit 415 ab, das Skript läuft dann nicht. |
| maximale Dateigröße (MB) | Obergrenze für Uploads in MB. Leer oder 0 bedeutet 25 MB. Darüber antwortet der Server mit 413. |
| Aktiv | Nur aktive Endpunkte sind erreichbar. Ein inaktiver Endpunkt antwortet mit 404. |
Das Skript des Endpunkts bearbeiten Sie in der Liste mit F7.
Routing über Pfad-Templates
Der Server ordnet jede Anfrage über das Pfad-Template einem Endpunkt zu:
- Statische Segmente müssen übereinstimmen. Groß- und Kleinschreibung spielt keine Rolle.
- Platzhalter in geschweiften Klammern, z.B.
{uid}, passen auf jeden Wert. Der Wert steht dem Skript als Pfad-Parameter zur Verfügung. - Die Zahl der Segmente muss gleich sein.
/orderspasst nicht auf/orders/{uid}.
| Template | Passt auf | Pfad-Parameter |
|---|---|---|
/orders |
/orders |
– |
/orders/{uid} |
/orders/4711 |
uid = 4711
|
/orders/{uid}/modules/{code} |
/orders/4711/modules/A1 |
uid = 4711, code = A1
|
/kalender/v1 |
/kalender/v1 |
– |
Passen mehrere Templates, gewinnt das spezifischste, also das mit den meisten statischen Segmenten. So schlägt /orders/summary das Template /orders/{uid}, während /orders/4711 auf /orders/{uid} passt. Haben zwei Templates gleich viele statische Segmente, ist nicht festgelegt, welches gewinnt. Vermeiden Sie solche Überschneidungen.
Passt kein Template, antwortet der Server mit 404 NOT_FOUND. Weitere Regeln, z.B. zu Schrägstrichen und Query-Parametern, beschreibt HTTP-Schnittstelle.
Pfad-Parameter im Skript
Das Skript liest die Werte der Platzhalter über oReader.Path:
procedure Get(oReader: TxRestReader; oWriter: TxRestWriter);
var cUid: string;
begin
cUid := oReader.Path('uid'); // aus /orders/{uid}
end;
Der Name des Parameters ist geschützt: Query-Parameter oder Header können ihn nicht überschreiben. Der Wert kommt aber aus der Adresse, die der Client sendet. Prüfen Sie ihn im Skript wie jede andere Eingabe. Details: Scripting.
URL-Struktur
https://<Host>[:<Port>]<Pfad-Template>
Beispiele:
https://obs.example.com/ordershttps://obs.example.com/orders/4711https://obs.example.com/orders/4711/modules/A1
HTTP-Methode
Der Server ruft im Skript die Methode auf, die zum HTTP-Verb passt: Get, Post, Put, Patch oder Delete. Fehlt die Methode im Skript, antwortet er mit 405 und nennt im Header Allow die vorhandenen.
Ein Template entspricht damit einem Skript. Unterschiedliche Pfad-Formen wie /orders und /orders/{uid} sind eigene Endpunkte mit eigenem Skript und eigener Berechtigung.
Schreibende Aufrufe (POST, PUT, PATCH, DELETE) schützt der Server selbst gegen doppelte Ausführung. Der Client sendet dafür den Header Idempotency-Key, am Endpunkt ist nichts einzustellen. Details: HTTP-Schnittstelle.
Versionierung
Die Version eines Endpunkts nehmen Sie als statisches Segment ins Template auf, z.B. /orders/v1 oder /v1/orders/{uid}. Eine Änderung ohne Bruch für bestehende Clients:
- Lassen Sie den bestehenden Endpunkt unverändert.
- Legen Sie einen neuen Endpunkt mit neuem Versions-Segment an.
- Vergeben Sie die Berechtigungen für die Clients, die umstellen.
- Deaktivieren Sie den alten Endpunkt, wenn alle Clients umgestellt sind.
Zugriffskontrolle
Ein Zugang darf einen Endpunkt nur nutzen, wenn er dafür berechtigt ist. Die Berechtigungen stehen in der Tabelle RESTSRV_ACCESS.
So vergeben Sie eine Berechtigung:
- Markieren Sie den Endpunkt in der Liste und drücken Sie F6. Die Liste Endpunkt Zugang zeigt die berechtigten Zugänge.
- Drücken Sie Einfg. Die Liste der Zugänge öffnet sich zur Auswahl.
- Markieren Sie die gewünschten Zugänge mit F5 und übernehmen Sie sie mit F2.
FORBIDDEN_ROLE und der Meldung „Zugriff verweigert“. Im Protokoll steht „Keine Berechtigung fuer die Endpunkt-Nutzung“. Vergeben Sie deshalb beim Anlegen immer auch die Berechtigung, und prüfen Sie bei einem 403 zuerst, ob sie existiert.Weil jede Pfad-Form ein eigener Endpunkt ist, vergeben Sie die Rechte je Pfad-Form. So erlauben Sie z.B. das Lesen von /orders/{uid}, aber nicht das Ändern über /orders/{uid}/modules/{code}.
Dateien
- Upload: Mit Datei-Upload nimmt der Endpunkt Dateien an, bis zur maximalen Dateigröße (MB). Übertragungsarten, Header und Statuscodes beschreibt Datei-Upload.
- Download: Jeder Endpunkt kann statt JSON eine Datei liefern, ohne Einstellung am Endpunkt. Das Skript erzeugt die Datei-Antwort, siehe Datei-Download.
Caching
Der Server hält die Endpunkte eines Server-Profils samt Skript 60 Sekunden im Speicher. Neue oder geänderte Endpunkte, Templates und Skripte wirken deshalb spätestens nach 60 Sekunden. Nach einem Neustart des REST-Dienstes wirken sie sofort.
WebHooks
Ein WebHook ist ein Endpunkt für einen einmaligen Rückruf. Typischer Einsatz: OBS stößt einen Vorgang bei einem Fremdsystem an, z.B. einem Bezahldienst oder Versanddienstleister, und gibt ihm eine Rückruf-Adresse mit, die nur einmal gilt. Die Adresse lässt sich danach nicht erneut oder von anderen benutzen.
Ablauf:
- OBS legt einen Eintrag in der Tabelle
REMOTE_HOOK_URLan und dazu einen Endpunkt, der auf diesen Eintrag verweist. Ein Skript hat dieser Endpunkt nicht. - Die Adresse dieses Endpunkts erhält das Fremdsystem als Rückruf-Adresse.
- Das Fremdsystem ruft die Adresse auf. Der Server speichert den empfangenen Inhalt in
REMOTE_HOOK_URL.hu_response, antwortet mit{"status": "ok"}und löscht den Endpunkt. - Der weiterverarbeitende OBS-Vorgang liest die Rückmeldung aus
hu_response.
Für den Aufruf gilt:
- Wie bei jedem Endpunkt prüft der Server API-Key und Berechtigung des Zugangs.
- Ein
Idempotency-Keyist nicht nötig. - Ein zweiter Aufruf derselben Adresse erhält sofort 404. Das ist gewollt: Ein WebHook ist keine dauerhafte Schnittstelle. Für eine dauerhafte Rückmelde-Adresse legen Sie einen normalen Endpunkt mit Skript an.
- Fehlt der Eintrag in
REMOTE_HOOK_URL, antwortet der Server mit 500.