OBS/Kostenpflichtige Module/RESTServer/Endpunkte: Unterschied zwischen den Versionen
Keine Bearbeitungszusammenfassung |
Keine Bearbeitungszusammenfassung |
||
| Zeile 40: | Zeile 40: | ||
{| class="wikitable" | {| class="wikitable" | ||
! Feld !! Spalte !! Zweck | ! Feld !! Spalte !! Zweck | ||
|- | |- | ||
| '''Pfad-Template''' || <code>re_pathtemplate</code> || '''Maßgeblich fürs Routing.''' Vollständiger Pfad mit Platzhaltern, z. B. <code>/orders/{uid}/modules/{code}</code> | | '''Pfad-Template''' || <code>re_pathtemplate</code> || '''Maßgeblich fürs Routing.''' Vollständiger Pfad mit Platzhaltern, z. B. <code>/orders/{uid}/modules/{code}</code> | ||
| Zeile 55: | Zeile 53: | ||
| '''Info''' || – || Dokumentations-Freitext | | '''Info''' || – || Dokumentations-Freitext | ||
|} | |} | ||
== Pfad-Parameter im Skript == | == Pfad-Parameter im Skript == | ||
Aktuelle Version vom 15. Juni 2026, 08:05 Uhr
- 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 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 (re_pathtemplate).
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.
{uid}– passen auf einen beliebigen Wert und werden als Pfad-Parameter erfasst.
Beispiele für gültige Templates:
| 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 |
– |
Präzedenz bei mehreren Treffern
Passen mehrere Templates auf denselben Pfad, 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} matcht.
Hauptfelder eines Endpunkts
| Feld | Spalte | Zweck |
|---|---|---|
| Pfad-Template | re_pathtemplate |
Maßgeblich fürs Routing. Vollständiger Pfad mit Platzhaltern, z. B. /orders/{uid}/modules/{code}
|
| Server | re_server |
Zuordnung zum Server-Profil (erforderlich) |
| Aktiv | re_aktiv |
Statusflag; inaktive Endpunkte liefern 404 |
| Skript | re_script |
DwScript-Quelltext des Handlers (siehe Scripting) |
| WebHook | re_webhook |
optional: Verweis auf einen Einmal-Endpunkt statt Skript |
| Info | – | Dokumentations-Freitext |
Pfad-Parameter im Skript
Die aus den Platzhaltern erfassten Werte stehen im Endpunkt-Skript als
reservierte Parameter mit Präfix _OBS_PATH_ zur Verfügung:
function Get(oParams: TStrings; oBody: TJSONObject): string;
var cUid: string;
begin
cUid := oParams.Values['_OBS_PATH_uid']; // aus /orders/{uid}
// ...
end;
Da der Präfix _OBS_ 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 (Get/Post/Put/Delete/Patch).
Ein Template entspricht damit einem Endpunkt-Skript; unterschiedliche
Pfad-Formen (z. B. /orders vs. /orders/{uid}) sind
eigene Endpunkt-Einträge mit eigenem Skript und eigener Berechtigung.
URL-Struktur
http://[Host][:Port][Pfad-Template]
Beispiele:
https://api.meinserver.de/ordershttps://api.meinserver.de/orders/4711https://api.meinserver.de/orders/4711/modules/A1
Versionierung
Da es kein eigenes Versions-Feld mehr gibt, wird die Version als statisches
Segment ins Template aufgenommen, z. B. /orders/v1 oder
/v1/orders/{uid}. Ä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 RESTSRV_ACCESS), 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
/orders/{uid} erlauben, aber das ändernde
PUT /orders/{uid}/modules/{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
| 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 RESTSRV_PROTO)
|
WebHooks
WebHooks sind Einmal-Endpunkte für asynchrone Callbacks. Beim ersten
erfolgreichen Aufruf wird die Antwort in der Tabelle REMOTE_HOOK_URL
gespeichert und der Endpunkt anschließend automatisch gelöscht.