|
|
| (17 dazwischenliegende Versionen von 2 Benutzern werden nicht angezeigt) |
| Zeile 1: |
Zeile 1: |
| {{Kostenpflichtige Module}}
| | #WEITERLEITUNG [[OBS/Kostenpflichtige Module/REST-Server/Pflege#Endpunkt]] |
| = Endpunkte =
| |
| | |
| Ein '''Endpunkt''' stellt eine Adresse bereit, über die der REST-Server konkrete
| |
| Funktionen anbietet. Jeder Endpunkt wird durch ein OBS-Skript oder einen WebHook
| |
| realisiert und ist genau einem Server-Profil zugeordnet.
| |
| | |
| == Routing über Pfad-Templates ==
| |
| | |
| Das Routing erfolgt über die Spalte '''Pfad-Template''' (<code>re_pathtemplate</code>).
| |
| Ein Template beschreibt den vollständigen Pfad nach dem Host und kann
| |
| '''Platzhalter''' enthalten:
| |
| | |
| * '''Statische Segmente''' müssen exakt übereinstimmen (Groß-/Kleinschreibung wird ignoriert).
| |
| * '''Platzhalter''' in geschweiften Klammern – z. B. <code>{uid}</code> – passen auf einen beliebigen Wert und werden als [[#Pfad-Parameter im Skript|Pfad-Parameter]] erfasst.
| |
| | |
| Beispiele für gültige Templates:
| |
| | |
| {| class="wikitable"
| |
| ! Template !! Passt auf !! Pfad-Parameter
| |
| |-
| |
| | <code>/orders</code> || <code>/orders</code> || –
| |
| |-
| |
| | <code>/orders/{uid}</code> || <code>/orders/4711</code> || <code>uid = 4711</code>
| |
| |-
| |
| | <code>/orders/{uid}/modules/{code}</code> || <code>/orders/4711/modules/A1</code> || <code>uid = 4711</code>, <code>code = A1</code>
| |
| |-
| |
| | <code>/kalender/v1</code> || <code>/kalender/v1</code> || –
| |
| |}
| |
| | |
| === Präzedenz bei mehreren Treffern ===
| |
| | |
| Passen mehrere Templates auf denselben Pfad, '''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> matcht.
| |
| | |
| == Hauptfelder eines Endpunkts ==
| |
| | |
| {| class="wikitable"
| |
| ! Feld !! Spalte !! Zweck
| |
| |-
| |
| | '''Endpunkt''' || <code>re_endpoint</code> || Ressourcen-/Anzeigename (z. B. <code>orders</code>). '''Hinweis:''' wird seit Umstellung auf Pfad-Templates '''nicht mehr für das Routing''' ausgewertet, dient nur noch der Übersicht/Gruppierung. Sinnvoll: erstes statisches Segment des Templates eintragen.
| |
| |-
| |
| | '''Pfad-Template''' || <code>re_pathtemplate</code> || '''Maßgeblich fürs Routing.''' Vollständiger Pfad mit Platzhaltern, z. B. <code>/orders/{uid}/modules/{code}</code>
| |
| |-
| |
| | '''Server''' || <code>re_server</code> || Zuordnung zum Server-Profil (erforderlich)
| |
| |-
| |
| | '''Aktiv''' || <code>re_aktiv</code> || Statusflag; inaktive Endpunkte liefern 404
| |
| |-
| |
| | '''Skript''' || <code>re_script</code> || DwScript-Quelltext des Handlers (siehe [[/OBS/Kostenpflichtige_Module/RESTServer/Scripting|Scripting]])
| |
| |-
| |
| | '''WebHook''' || <code>re_webhook</code> || optional: Verweis auf einen Einmal-Endpunkt statt Skript
| |
| |-
| |
| | '''Info''' || – || Dokumentations-Freitext
| |
| |}
| |
| | |
| {{Hinweis|Die früheren Felder '''Sub-URL''' (<code>re_suburl</code>) und
| |
| '''Version''' (<code>re_version</code>) werden vom Routing '''nicht mehr
| |
| ausgewertet'''. Die Version wird – falls benötigt – als statisches Segment Teil
| |
| des Pfad-Templates (siehe [[#Versionierung|Versionierung]]).}}
| |
| | |
| == Pfad-Parameter im Skript ==
| |
| | |
| Die aus den Platzhaltern erfassten Werte stehen im Endpunkt-Skript als
| |
| reservierte Parameter mit Präfix <code>_OBS_PATH_</code> zur Verfügung:
| |
| | |
| <syntaxhighlight lang="pascal">
| |
| function Get(oParams: TStrings; oBody: TJSONObject): string;
| |
| var cUid: string;
| |
| begin
| |
| cUid := oParams.Values['_OBS_PATH_uid']; // aus /orders/{uid}
| |
| // ...
| |
| end;
| |
| </syntaxhighlight>
| |
| | |
| Da der Präfix <code>_OBS_</code> für von außen gelieferte Header/Query-Parameter
| |
| gesperrt ist, können diese Werte nicht durch den Client überschrieben werden.
| |
| | |
| == HTTP-Methode ==
| |
| | |
| Welche Funktion aufgerufen wird, ergibt sich aus dem HTTP-Verb: Der Server ruft
| |
| die gleichnamige Skript-Methode auf (<code>Get</code>/<code>Post</code>/<code>Put</code>/<code>Delete</code>/<code>Patch</code>).
| |
| Ein Template entspricht damit '''einem''' Endpunkt-Skript; unterschiedliche
| |
| Pfad-Formen (z. B. <code>/orders</code> vs. <code>/orders/{uid}</code>) sind
| |
| '''eigene Endpunkt-Einträge''' mit eigenem Skript und eigener Berechtigung.
| |
| | |
| == URL-Struktur ==
| |
| | |
| <pre>
| |
| http://[Host][:Port][Pfad-Template]
| |
| </pre>
| |
| | |
| Beispiele:
| |
| * <code>https://api.meinserver.de/orders</code>
| |
| * <code>https://api.meinserver.de/orders/4711</code>
| |
| * <code>https://api.meinserver.de/orders/4711/modules/A1</code>
| |
| | |
| == Versionierung ==
| |
| | |
| Da es kein eigenes Versions-Feld mehr gibt, wird die Version als statisches
| |
| Segment ins Template aufgenommen, z. B. <code>/orders/v1</code> oder
| |
| <code>/v1/orders/{uid}</code>. Änderung ohne Breaking Change:
| |
| | |
| # Bestehenden Endpunkt unverändert lassen.
| |
| # Neuen Endpunkt mit gleichem Ressourcennamen, aber neuem Versions-Segment im Template anlegen.
| |
| # Berechtigungen für neue Konsumenten setzen.
| |
| # Alten Endpunkt deaktivieren, wenn die Migration abgeschlossen ist. | |
| | |
| == Zugriffskontrolle ==
| |
| | |
| Endpunkte sind Server-Profilen zugeordnet; ein Zugang benötigt eine explizite
| |
| Berechtigung (Tabelle <code>RESTSRV_ACCESS</code>), um einen Endpunkt nutzen zu
| |
| dürfen. Weil jede Pfad-Form ein eigener Endpunkt-Eintrag ist, lässt sich der
| |
| Zugriff '''pro Pfad-Form''' granular vergeben (z. B. Lesen von
| |
| <code>/orders/{uid}</code> erlauben, aber das ändernde
| |
| <code>PUT /orders/{uid}/modules/{code}</code> nicht).
| |
| | |
| == Caching ==
| |
| | |
| Die Endpunkt-Definitionen werden pro Server-Profil zwischengespeichert
| |
| (TTL, Standard 60 s). Neue oder geänderte Endpunkte/Templates werden daher
| |
| erst nach Ablauf des Caches (bzw. nach einer Cache-Invalidierung) wirksam – nicht
| |
| zwingend sofort.
| |
| | |
| == HTTP-Fehlercodes ==
| |
| | |
| {| class="wikitable"
| |
| ! Code !! Ursache
| |
| |-
| |
| | '''404''' || Kein Template passt zum Pfad, Endpunkt inaktiv oder falsches Server-Profil
| |
| |-
| |
| | '''403''' || Zugang fehlt in der Berechtigungsliste
| |
| |-
| |
| | '''401''' || API-Key ungültig/fehlend oder JWT abgelaufen
| |
| |-
| |
| | '''500''' || Skript- oder Syntax-Fehler (Details in <code>RESTSRV_PROTO</code>)
| |
| |}
| |
| | |
| == WebHooks ==
| |
| | |
| WebHooks sind '''Einmal-Endpunkte''' für asynchrone Callbacks. Beim ersten
| |
| erfolgreichen Aufruf wird die Antwort in der Tabelle <code>REMOTE_HOOK_URL</code>
| |
| gespeichert und der Endpunkt anschließend automatisch gelöscht.
| |
| | |
| == Siehe auch ==
| |
| | |
| * [[/OBS/Kostenpflichtige_Module/RESTServer/Scripting|Scripting]]
| |
| * [[/OBS/Kostenpflichtige_Module/RESTServer/Beispiel4|Beispiel 4 – Pfad-Parameter]]
| |