OBS/Kostenpflichtige Module/RESTServer/Endpunkte: Unterschied zwischen den Versionen

Aus OBS Wiki
Zur Navigation springen Zur Suche springen
(Die Seite wurde neu angelegt: „22 year old Conveyancer Nestor from Igloolik, spends time with pursuits which include body building, mobile games and collecting music albums. Has enrolled in…“)
 
Keine Bearbeitungszusammenfassung
 
(Eine dazwischenliegende Version desselben Benutzers wird nicht angezeigt)
Zeile 1: Zeile 1:
22 year old Conveyancer Nestor from Igloolik, spends time with pursuits which include body building, mobile games and collecting music albums. Has enrolled in a global contiki voyage. Is quite excited particularly about visiting Muskauer Park / Park Muzakowski.<br><br>Look into my page ... [http://mombao3.livejournal.com/620.html legends of tomorrow cast amaya]
{{Kostenpflichtige Module}}
 
=Endpunkte=
 
Ein '''Endpunkt''' definiert eine Adresse, über die der REST-Server eine konkrete Funktion anbietet. Hinter jedem Endpunkt steht entweder ein OBS-Skript (Standardfall) oder ein WebHook (Einmal-Antwort für asynchrone Rückrufe).
 
==Aufruf==
 
'''Stammdaten -> Z Weitere Stammdaten -> REST-Server -> Endpunkte'''
 
==Felder==
 
{| class="wikitable"
! 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 über 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, verkürzt sich die Adresse auf ''/Endpunkt/Version''.
 
==Versionierung==
 
Die Versionierung erlaubt es, eine Endpunkt-Funktionalität zu ändern, ohne bestehende Konsumenten zu brechen. Das Vorgehen:
 
# Den vorhandenen Endpunkt unverändert lassen, weiterhin aktiv halten.
# Einen neuen Endpunkt mit gleicher Endpunkt-/Sub-URL, aber neuer Version anlegen.
# Berechtigungen für 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 über das Public-Profil zugreift, kann nicht versehentlich die mTLS-Variante ansprechen.
 
==Berechtigungen==
 
Damit ein Zugang einen Endpunkt aufrufen darf, muss er für diesen Endpunkt freigeschaltet sein. Aus der Endpunkt-Liste den Endpunkt markieren und '''F6''' drücken. Es öffnet sich die Berechtigungs-Liste.
 
In der Berechtigungs-Liste:
 
* '''Einfg''' - öffnet die Zugänge-Liste.
* In der Zugänge-Liste mit '''F5''' einen oder mehrere Zugänge markieren.
* '''F2''' übernimmt die markierten Zugänge als Berechtigungen.
 
Ohne Markierung wird nur der aktuelle Zugang übernommen.
 
==Endpunkt-Skript==
 
Aus der Endpunkt-Liste den Endpunkt markieren und '''F7''' drücken. Es öffnet 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 verfügbaren Parameter sind unter [[OBS/Kostenpflichtige Module/RESTServer/Scripting|Scripting]] beschrieben.
 
==WebHooks==
 
Ein Endpunkt kann alternativ als WebHook konfiguriert werden. WebHooks sind '''Einmal-Endpunkte''' - sie werden in der Regel von OBS aus dynamisch für externe Dienste angelegt (z.B. Bezahl-Callbacks). Beim ersten erfolgreichen Aufruf:
 
# Die übergebenen 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''' gelöscht.
# Der Server antwortet mit ''{"status": "ok"}''.
 
Damit lassen sich asynchrone Rückrufe sauber konsumieren, ohne dass dauerhaft offene Endpunkte zurückbleiben. Die Anlage und Auswertung eines WebHooks erfolgt typischerweise programmgesteuert über die zugehörigen Helper-Funktionen, nicht über die Endpunkt-Maske.
 
==Listen-Funktionen==
 
In der Endpunkt-Liste:
 
* '''Einfg''' - neuer Endpunkt
* '''Return''' - Endpunkt bearbeiten
* '''F4''' - Sortierung
* '''F6''' - Berechtigungen verwalten (Zugänge dem Endpunkt zuordnen)
* '''F7''' - Endpunkt-Skript bearbeiten
* '''F8''' - Statistik für den Endpunkt
 
==Cache==
 
Der REST-Server cached das kompilierte Skript pro Endpunkt. Wird das Skript über F7 geändert, ist die neue Version sofort wirksam - der Server erkennt die Änderung am ''sys_date'' und compiliert neu.
 
==Typische Fehlermeldungen==
 
{| class="wikitable"
! Code  !! Bedeutung
|-
| 404  || Endpunkt nicht vorhanden / inaktiv / falsches Server-Profil
|-
| 403  || Keine Berechtigung für die Endpunkt-Nutzung (Zugang fehlt in der Berechtigungs-Liste)
|-
| 401  || API-Key fehlt, ungültig, JWT fehlt oder ist abgelaufen
|-
| 500  || Skript-Fehler oder Syntax-Fehler im Endpunkt-Skript - Detail siehe RESTSRV_PROTO
|}

Aktuelle Version vom 19. Mai 2026, 07:12 Uhr

Kostenpflichtige Module

Internet-Shop
Der modified ECommerce Shop
Shop-Menü
Automatische Vorgänge
modified eCommerce 2.0
Der Büroring-ShopV4
Einrichtung
Eigene Artikel
brShop24
Einstellungen und Automatiken
Funktionen
Preislisten
Preislistenverwaltung
F10 Weitere Funktionen
Automatiken Kommandos
ZUGFeRD
Factoring
UPS
DHL
IMS Professional
TAPI
SMS
Fleet Management
Mehrlager-Verwaltung
Mehrsprachen Modul
Multilanguage Modul
Einfache Produktionsnachverfolgung
DMS - Dokumenten Management System
DMS Dokumente
Tasten und Schaltflächen
F10 Weit.
E DMS Definitionen
QR Zeiterfassung
EVA Marketing Tool
Technikersteuerung
Termin-Projekte
Edifact-Schnittstelle
Backup Überwachung Email
Anlagenbuchhaltung
OBS Geo Daten
DeliSprint / DPD
Filialen
Auto-Waagen
Cashback
Moebelschnittstelle
Tourenplanung
Tourenplanung
Dokumenten Manager
DocuWare-Schnittstelle
OFML-Kalkulation
Pascom
Versicherungsschaden
Gutschriftsanzeigen
OCPP Ladestationen
Kameraverwaltung
DataInOut
REST-Schnittstelle
Beispiele
Sammelverträge
Craftboxx
OpenMasterData / IDS
Sammelpositionen


Endpunkte

Ein Endpunkt definiert eine Adresse, über die der REST-Server eine konkrete Funktion anbietet. Hinter jedem Endpunkt steht entweder ein OBS-Skript (Standardfall) oder ein WebHook (Einmal-Antwort für asynchrone Rückrufe).

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 über 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, verkürzt sich die Adresse auf /Endpunkt/Version.

Versionierung

Die Versionierung erlaubt es, eine Endpunkt-Funktionalität zu ändern, ohne bestehende Konsumenten zu brechen. Das Vorgehen:

  1. Den vorhandenen Endpunkt unverändert lassen, weiterhin aktiv halten.
  2. Einen neuen Endpunkt mit gleicher Endpunkt-/Sub-URL, aber neuer Version anlegen.
  3. Berechtigungen für die neuen Konsumenten setzen.
  4. 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 über das Public-Profil zugreift, kann nicht versehentlich die mTLS-Variante ansprechen.

Berechtigungen

Damit ein Zugang einen Endpunkt aufrufen darf, muss er für diesen Endpunkt freigeschaltet sein. Aus der Endpunkt-Liste den Endpunkt markieren und F6 drücken. Es öffnet sich die Berechtigungs-Liste.

In der Berechtigungs-Liste:

  • Einfg - öffnet die Zugänge-Liste.
  • In der Zugänge-Liste mit F5 einen oder mehrere Zugänge markieren.
  • F2 übernimmt die markierten Zugänge als Berechtigungen.

Ohne Markierung wird nur der aktuelle Zugang übernommen.

Endpunkt-Skript

Aus der Endpunkt-Liste den Endpunkt markieren und F7 drücken. Es öffnet 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 verfügbaren 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 für externe Dienste angelegt (z.B. Bezahl-Callbacks). Beim ersten erfolgreichen Aufruf:

  1. Die übergebenen Daten (Query-String oder Request-Body) werden in der Tabelle REMOTE_HOOK_URL im Feld hu_response gespeichert.
  2. Der Endpunkt wird automatisch aus RESTSRV_ENDPOINTS gelöscht.
  3. Der Server antwortet mit {"status": "ok"}.

Damit lassen sich asynchrone Rückrufe sauber konsumieren, ohne dass dauerhaft offene Endpunkte zurückbleiben. Die Anlage und Auswertung eines WebHooks erfolgt typischerweise programmgesteuert über die zugehörigen Helper-Funktionen, nicht über die Endpunkt-Maske.

Listen-Funktionen

In der Endpunkt-Liste:

  • Einfg - neuer Endpunkt
  • Return - Endpunkt bearbeiten
  • F4 - Sortierung
  • F6 - Berechtigungen verwalten (Zugänge dem Endpunkt zuordnen)
  • F7 - Endpunkt-Skript bearbeiten
  • F8 - Statistik für den Endpunkt

Cache

Der REST-Server cached das kompilierte Skript pro Endpunkt. Wird das Skript über F7 geändert, ist die neue Version sofort wirksam - der Server erkennt die Änderung am sys_date und compiliert neu.

Typische Fehlermeldungen

Code Bedeutung
404 Endpunkt nicht vorhanden / inaktiv / falsches Server-Profil
403 Keine Berechtigung für die Endpunkt-Nutzung (Zugang fehlt in der Berechtigungs-Liste)
401 API-Key fehlt, ungültig, JWT fehlt oder ist abgelaufen
500 Skript-Fehler oder Syntax-Fehler im Endpunkt-Skript - Detail siehe RESTSRV_PROTO
Abgerufen von „http:///index.php?title=OBS/Kostenpflichtige_Module/RESTServer/Endpunkte&oldid=64462“