OBS/Kostenpflichtige Module/REST-Server/Endpunkte: Unterschied zwischen den Versionen
K MINERVA-Rademacker verschob die Seite OBS/Kostenpflichtige Module/RESTServer/Endpunkte nach OBS/Kostenpflichtige Module/REST-Server/Endpunkte: Titel an Überschrift angeglichen (REST-Server, Umlaute, sprechende Beispieltitel) |
Links auf die neuen Titel (REST-Server, Zugänge, Beispiele) umgestellt, zitierte Meldungen mit Umlauten wie im Programm [Volltext ersetzt] |
||
| Zeile 20: | Zeile 20: | ||
| {{F6}} || Schaltfläche '''F6 Zugang''': öffnet die Liste der Zugänge, die diesen Endpunkt nutzen dürfen, siehe [[#Zugriffskontrolle|Zugriffskontrolle]]. | | {{F6}} || Schaltfläche '''F6 Zugang''': öffnet die Liste der Zugänge, die diesen Endpunkt nutzen dürfen, siehe [[#Zugriffskontrolle|Zugriffskontrolle]]. | ||
|- | |- | ||
| {{F7}} || Schaltfläche '''F7 Script''': öffnet das Skript des Endpunkts im Skript-Editor. Wie Sie es schreiben, beschreibt [[OBS/Kostenpflichtige Module/ | | {{F7}} || Schaltfläche '''F7 Script''': öffnet das Skript des Endpunkts im Skript-Editor. Wie Sie es schreiben, beschreibt [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]]. | ||
|- | |- | ||
| {{F8}} || Schaltfläche '''F8 Stat''': zeigt die Statistik der Anfragen an diesen Endpunkt. | | {{F8}} || Schaltfläche '''F8 Stat''': zeigt die Statistik der Anfragen an diesen Endpunkt. | ||
| Zeile 66: | Zeile 66: | ||
Passen mehrere Templates, gewinnt das spezifischste, also das mit den meisten statischen Segmenten. So schlägt <code>/orders/summary</code> das Template <code>/orders/{uid}</code>, während <code>/orders/4711</code> auf <code>/orders/{uid}</code> passt. Haben zwei Templates gleich viele statische Segmente, ist nicht festgelegt, welches gewinnt. Vermeiden Sie solche Überschneidungen. | Passen mehrere Templates, gewinnt das spezifischste, also das mit den meisten statischen Segmenten. So schlägt <code>/orders/summary</code> das Template <code>/orders/{uid}</code>, während <code>/orders/4711</code> auf <code>/orders/{uid}</code> 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''' <code>NOT_FOUND</code>. Weitere Regeln, z.B. zu Schrägstrichen und Query-Parametern, beschreibt [[OBS/Kostenpflichtige Module/ | Passt kein Template, antwortet der Server mit '''404''' <code>NOT_FOUND</code>. Weitere Regeln, z.B. zu Schrägstrichen und Query-Parametern, beschreibt [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle#Adressierung|HTTP-Schnittstelle]]. | ||
=== Pfad-Parameter im Skript === | === Pfad-Parameter im Skript === | ||
| Zeile 79: | Zeile 79: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
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: [[OBS/Kostenpflichtige Module/ | 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: [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]]. | ||
=== URL-Struktur === | === URL-Struktur === | ||
| Zeile 96: | Zeile 96: | ||
Ein Template entspricht damit einem Skript. Unterschiedliche Pfad-Formen wie <code>/orders</code> und <code>/orders/{uid}</code> sind eigene Endpunkte mit eigenem Skript und eigener Berechtigung. | Ein Template entspricht damit einem Skript. Unterschiedliche Pfad-Formen wie <code>/orders</code> und <code>/orders/{uid}</code> sind eigene Endpunkte mit eigenem Skript und eigener Berechtigung. | ||
Schreibende Aufrufe (<code>POST</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code>) schützt der Server selbst gegen doppelte Ausführung. Der Client sendet dafür den Header <code>Idempotency-Key</code>, am Endpunkt ist nichts einzustellen. Details: [[OBS/Kostenpflichtige Module/ | Schreibende Aufrufe (<code>POST</code>, <code>PUT</code>, <code>PATCH</code>, <code>DELETE</code>) schützt der Server selbst gegen doppelte Ausführung. Der Client sendet dafür den Header <code>Idempotency-Key</code>, am Endpunkt ist nichts einzustellen. Details: [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle#Idempotenz|HTTP-Schnittstelle]]. | ||
== Versionierung == | == Versionierung == | ||
| Zeile 113: | Zeile 113: | ||
# Markieren Sie die gewünschten Zugänge mit {{F5}} und übernehmen Sie sie mit {{F2}}. | # Markieren Sie die gewünschten Zugänge mit {{F5}} und übernehmen Sie sie mit {{F2}}. | ||
{{Achtung|Ein Endpunkt ohne Berechtigung sieht fertig aus: Pfad, Skript und Server-Profil stimmen, der Aufruf scheitert trotzdem mit '''403''' <code>FORBIDDEN_ROLE</code> und der Meldung „Zugriff verweigert“. Im Protokoll steht „Keine Berechtigung | {{Achtung|Ein Endpunkt ohne Berechtigung sieht fertig aus: Pfad, Skript und Server-Profil stimmen, der Aufruf scheitert trotzdem mit '''403''' <code>FORBIDDEN_ROLE</code> und der Meldung „Zugriff verweigert“. Im Protokoll steht „Keine Berechtigung für 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 <code>/orders/{uid}</code>, aber nicht das Ändern über <code>/orders/{uid}/modules/{code}</code>. | Weil jede Pfad-Form ein eigener Endpunkt ist, vergeben Sie die Rechte je Pfad-Form. So erlauben Sie z.B. das Lesen von <code>/orders/{uid}</code>, aber nicht das Ändern über <code>/orders/{uid}/modules/{code}</code>. | ||
== Dateien == | == Dateien == | ||
* '''Upload:''' Mit '''Datei-Upload''' nimmt der Endpunkt Dateien an, bis zur '''maximalen Dateigröße (MB)'''. Übertragungsarten, Header und Statuscodes beschreibt [[OBS/Kostenpflichtige Module/ | * '''Upload:''' Mit '''Datei-Upload''' nimmt der Endpunkt Dateien an, bis zur '''maximalen Dateigröße (MB)'''. Übertragungsarten, Header und Statuscodes beschreibt [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]]. | ||
* '''Download:''' Jeder Endpunkt kann statt JSON eine Datei liefern, ohne Einstellung am Endpunkt. Das Skript erzeugt die Datei-Antwort, siehe [[OBS/Kostenpflichtige Module/ | * '''Download:''' Jeder Endpunkt kann statt JSON eine Datei liefern, ohne Einstellung am Endpunkt. Das Skript erzeugt die Datei-Antwort, siehe [[OBS/Kostenpflichtige Module/REST-Server/Datei-Download|Datei-Download]]. | ||
== Caching == | == Caching == | ||
| Zeile 140: | Zeile 140: | ||
== Siehe auch == | == Siehe auch == | ||
* [[OBS/Kostenpflichtige Module/ | * [[OBS/Kostenpflichtige Module/REST-Server/Scripting|Scripting]] | ||
* [[OBS/Kostenpflichtige Module/ | * [[OBS/Kostenpflichtige Module/REST-Server/Zugänge|Zugänge]] | ||
* [[OBS/Kostenpflichtige Module/ | * [[OBS/Kostenpflichtige Module/REST-Server/HTTP-Schnittstelle|HTTP-Schnittstelle]] | ||
* [[OBS/Kostenpflichtige Module/ | * [[OBS/Kostenpflichtige Module/REST-Server/Datei-Upload|Datei-Upload]] | ||
* [[OBS/Kostenpflichtige Module/ | * [[OBS/Kostenpflichtige Module/REST-Server/Datei-Download|Datei-Download]] | ||
* [[OBS/Kostenpflichtige Module/ | * [[OBS/Kostenpflichtige Module/REST-Server/Einrichtung|Einrichtung]] | ||
Version vom 17. November 2026, 07:23 Uhr
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 für 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.