API-Manager

Der Menüeintrag API-Manager erscheint im Menüknoten Integration wenn für die angemeldete Rolle (s. Rollen) ausreichende Berechtigungen vorliegen.

Ein Klick auf den Menüeintrag öffnet eine Übersicht für den Entitätstyp “API“ (RestApiDefinition).

View-Name: de.lobster.scm.api::RestApiDefinition|listSearchWindow
Menüknoten-Name: integrationModules/restApi

Den Zugriff auf “API”-Entitäten regelt der Berechtigungsknoten “Verwaltung/Konfiguration/(REST/MCP API)” (administration/designer/restApiDefinition).

Der Menüeintrag API-Manager erscheint nur, wenn für die Rolle der Session die Berechtigung "Anzeigen" (show) vorliegt.
Für den Zugriff auf “API”-Entitäten sind im Allgemeinen Besitzereinschränkungen für die Firma der Session zu berücksichtigen.
Die Berechtigungen der Rolle der Session sind daher nur für “API”-Entitäten wirksam, für die die Firma der Session als Besitzer gilt oder Empfänger von entsprechenden Firmenfreigaben ist.

Instanzen des Entitätstyps “API” (RestApiDefinition) definieren REST-Schnittstellen für den Lobster Data Platform-Server.

Die “API”-Instanz selbst ist nur eine äußere Hülle für die Verwaltung der im Feld “API” (api) eingebetteten API-Definition.

Als API-Definition kommt eine der folgenden REST-API-Klassen in Frage:

REST API (RestApi): definiert Endpunkte (für HTTP-Methoden) für allgemeine REST-Zugriffe.
MCP-Server (McpRestApi): definiert Tools für den Zugriff durch Künstliche Intelligenz (KI) per Model Context Protocol (MCP).

Unabhängig vom Typ der API-Definition stützt sich der Zugriff auf die Details einer konkreten “API”-Instanz auf dieselbe vordefinierte Erfassungsmaske (s. Erfassungsmasken). Allerdings variiert deren Erscheinungsbild abhängig vom Typ der ausgewählten API-Definition.

Die Erfassungsmaske wird über den View-Namen de.lobster.scm.api::RestApiDefinition|detailsWindow geöffnet, sofern ausreichende Berechtigungen vorliegen.

Der Zugriff auf die Erfassungsmaske erfolgt typischerweise ausgehend von der Übersicht, die der Menüeintrag API-Manager öffnet.

Ein Klick auf den Ribbon Button “Neu” (in der Übersicht) öffnet zunächst ein Kontextmenü, in dem der Typ der API-Definition ausgewählt werden muss.
WICHTIG Es existiert keine interaktive Methode, um diese Auswahl für eine bestehende “API”-Instanz nachträglich zu ändern. Typischerweise gilt die Auswahl also für den gesamten Lebenszyklus einer “API”-Instanz.
- Der Ribbon Button “Neu” erscheint nur, wenn die Rolle der Session über die Berechtigung “Erstellen” (create) verfügt.
- Die im Kontextmenü ausgewählte API-Definition für die neue “API”-Instanz bestimmt das Erscheinungsbild der geöffneten Erfassungsmaske.
Für genau eine ausgewählte “API”-Instanz öffnet ein Doppelklick oder der Ribbon Button “Bearbeiten” bzw. “Details anzeigen” die Erfassungsmaske mit den Daten dieser Instanz.
- Der Ribbon Button “Bearbeiten” erscheint nur, wenn die Rolle der Session über die Berechtigung “Ändern” (update) verfügt.
- Derselbe Ribbon Button erscheint mit der Beschriftung “Details anzeigen”, wenn die Rolle der Session nur über die Berechtigung zum “Anzeigen” (show) und/oder “Erstellen” (create) verfügt. Dort kann der volatile Datenstand sogar manipuliert werden. Allerdings erscheint der Ribbon Button “Speichern” deaktiviert. In Verbindung mit der Berechtigung zum “Erstellen” (create) kann allerdings der Ribbon Button “Kopieren” verwendet werden, um Anpassungen in eine neue “API”-Instanz zu übernehmen, die dann auch gespeichert werden kann.

Konfiguration

Die folgenden Abschnitte beschreiben die Konfigurationsmerkmale des Entitätstyps “API” (RestApiDefinition), die unabhängig vom gewählten Typ für die API-Definition gelten.

Jeder Abschnitt bezieht sich auf einen Tab-Reiter in der Erfassungsmaske.

HINWEIS Details zur spezifischen Tab-Reitern je API-Definition sind unter REST API bzw. MCP-Server zu finden (betrifft Tab-Reiter “API” und ggf. “Meta-Informationen”).

Grundeinstellungen

Eigenschaft	Datenfeld	Datentyp	Beschreibung
Aktiviert	`enabled`	`Boolean`	Über das Kennzeichen “Aktiviert” kann gesteuert werden, ob die zugehörige “API”-Instanz insgesamt operativ relevant sein soll (`true`) oder nicht (`false`). Per Standard ist das Kennzeichen abgewählt. Eine neu erstellte “API” muss also bewusst aktiviert werden, damit sie effektiv sein kann. HINWEIS Änderungen am Aktivierungsstatus werden erst beim Speichern der “API”-Instanz wirksam. Ob Änderungen am Aktivierungsstatus einer einzelnen “API”-Instanz unmittelbare operative Auswirkungen haben, kann vom Zusammenspiel mehrerer “API”-Instanzen abhängen, wenn diese Überschneidungen bei Tool- bzw. Endpoint-Definitionen im Kontext derselben “Basis-URI” bereitstellen (s. a. “Priorität” unten).
Besitzer	`ownerId`	`Long`	Als “Besitzer” wird im Regelfall die Firma der Session zugeordnet, in deren Kontext eine “API”-Instanz erstmalig gespeichert wird. Für Abweichende Zuordnungen stellt die Erfassungsmaske ein Auswahlfeld/Combobox-Element bereit. Besitzereinschränkungen sind nur für die Konfiguration einer “API”-Instanz relevant. Auf den operativen Zugriff haben Besitzereinschränkungen und Firmenfreigaben dagegen keinen unmittelbaren Einfluss.
Name	`name`	`String`	Jeder “API”-Instanz muss ein “Name” zugeordnet werden. Da die Entität durch die systemseitig zugewiesene “ID” (`id`) eindeutig identifiziert wird, muss der zugewiesene “Name” nicht unbedingt eindeutig sein. Er dient nur zur Orientierung im Kontext der Konfiguration und hat keinerlei operative Relevanz für die Schnittstelle.
Beschreibung	`description`	`String`	Das Textfeld “Beschreibung” kann optional einen mehrzeiligen Freitext beherbergen. Typischerweise dient diese dem Zweck, eine Konfiguration und/oder daran vorgenommene Änderungen zu dokumentieren. Das Feld hat keine operative Relevanz für die Schnittstelle. HINWEIS Zusätzlich können einer “API”-Instanz auch Tags zugewiesen werden, um sie zu kategorisieren. Dies ist insbesondere mit Blick auf den Transfer von solchen Konfigurationen zwischen Systemen per Meta Exchange empfehlenswert.
Priorität	`priority`	`Integer`	Die Eigenschaft “Priorität” enthält einen positiven oder negativen ganzzahligen Zahlenwert, der operativ ausschlaggebend für den Vorrang von “API”-Instanzen sein kann, wenn deren API-Definition denselben Kontext (definiert durch Basis-URI und Tool bzw. Endpoint) betreffen. Ist dies der Fall, greift im “Konfliktfall” für einen eingehenden Aufruf ausschließlich die anwendbare Tool- bzw. Endpoint-Definition aus der “API”-Instanz mit dem höchsten Wert für die “Priorität”. HINWEIS Das Deaktivieren (s. “Aktiviert”, oben) einer “API”-Instanz nimmt diese komplett aus dem Rennen um eingehende Aufrufe. Die Priorität einer inaktiven Konfiguration ist also irrelevant. Eine inaktive “API”-Instanz mit hoher Priorität fängt also nicht etwa eingehende Aufrufe für die enthaltenen Tools bzw. Endpoints ab.

Private Strukturen

Der Tab-Reiter für “Private Strukturen” ermöglicht das Anlegen privater Client-Objekt-Strukturen. Dabei handelt es sich um benutzerdefinierte Datenstrukturen, die über den zugeordneten “Alias” in Konfigurationen für die “API”-Instanz referenziert werden können (s. Client Objekt-Struktur Referenz). Sie werden als privat bezeichnet, weil ihre Nutzung exklusiv auf den Kontext der übergeordneten “API”-Instanz beschränkt ist.

Die Definition der Datenstruktur besteht in einer Auflistung aller Felder, die ein Client-Objekt enthalten kann bzw. muss, um dem “privaten Typ” zu entsprechen.

Der folgend eScreenshot zeigt ein Beispiel, in dem für den Kontext derselben “API”-Instanz zwei private Strukturen (Waypoint und Leg) definiert sind:

Die “Private Struktur” mit dem Alias Waypoint soll einen Wegpunkt entlang einer Flugverbindung definieren.
Im Feld location wird eine Zeichenfolge (String) erwartet, die den Wegpunkt eindeutig bezeichnet.
Im Feld locationType soll optional eine weitere Zeichenfolge (String) angegeben werden können, um zu signalisieren, dass als Text im location-Feld ein Code aus einem bestimmten Kontext angegeben wurde.
- Die Checkbox Optional (s. Popover im Bild) ist ausgewählt, sodass das Feld nicht verpflichtend vorhanden sein muss. Daher erscheint in der “Felder”-Liste ein ? als Suffix zum Feldnamen (locationType).
- Der Definition für das Feld wurde ein Text Werte Validierer (Client-Objektstruktur) hinzugefügt, der eine Positivliste für alle zulässigen locationType-Textwerte (hier: ICAO, IATA) festlegt.

Die zweite “Private Struktur” mit dem Alias Leg demonstriert hier eine mögliche Verwendung für “Private Strukturen”, in dem sie sich mehrfach auf die erste “Private Struktur” als Datentyp für eigene Felder bezieht.
Konkret kombiniert die Leg-Struktur zwei oder drei Waypoint-Instanzen zu einer Flugverbindung vom fromWaypoint zum toWaypoint mit der Möglichkeit über das Feld viaWaypoint ein “Zwischenziel” anzugeben.

Im Workflow für einen Endpunkt bzw. ein Tool der zugehörigen “API”-Definition kann z. B. auch die Prüfe Client-Objektstruktur (Regel) oder der Prüfe Client-Objektstruktur (Wertauflöser) mit Bezug zu einer dieser Strukturen eingesetzt werden, um Eingangsdaten zu validieren.

Andererseits könnte eine ‘Private Struktur’ auch im Erzeuge Instanz mit Werten-Wertauflöser referenziert werden, um die Felder eines Client-Objekts für den Rückgabewert (Variable response) bequem “ausfüllen” zu können:

ANMERKUNG In diesem Einsatzbeispiel wird die “Private Struktur” Waypoint nur als Client-Objektstruktur für das zu erstellende “Client-Objekt” referenziert, um die verfügbaren Felder als Ziel für eine Zuweisung über das Dropdown es Feld Eigenschaft auswählen zu können. Eine Prüfung, die auch den Text Werte Validierer (Client-Objektstruktur) für das Feld locationType mit dem zugewiesenen Wert (hier: ICAO) abgleichen würde, findet nicht statt. Dies könnte ein verketteter Prüfe Client-Objektstruktur (Wertauflöser) leisten.

Private Bausteine

Über den Tab-Reiter für “Private Bausteine” können Eigene Bausteine (s. dort für mehr Details) definiert werden. Diese werden als privat bezeichnet, weil ihre Nutzung exklusiv auf den Kontext der übergeordneten “API”-Instanz beschränkt ist.

Als “Private Bausteine” können Ereignisaktionen, Wertauflöser oder Regeltypen mit einer spezifischen Charakteristik deren Einsatz auf den Kontext der “API”-Instanz beschränkt sein soll.