API-Manager

Was ist der API-Manager?

Der API-Manager ist ein integriertes Modul der Lobster Data Platform. Er ermöglicht es, REST-Schnittstellen und MCP-Server direkt auf dem Lobster Data Platform-Server zu konfigurieren und zu betreiben. Ein externer Middleware-Layer ist dafür nicht erforderlich.

Über den API-Manager können Sie:

REST-APIs bereitstellen: Definieren Sie HTTP-Endpunkte, die externe Systeme per Standard-HTTP-Methoden aufrufen können.
MCP-Server einrichten: Stellen Sie Tools für KI-Agenten bereit. KI-Agenten rufen diese Tools über das Model Context Protocol (MCP) auf.
Zugriff kontrollieren: Steuern Sie über Rollen und Berechtigungen, wer API-Konfigurationen sehen, erstellen oder bearbeiten darf.
Prioritäten setzen: Bestimmen Sie, welche API-Instanz Vorrang hat, wenn mehrere Instanzen denselben Endpunkt oder dasselbe Tool definieren.

Voraussetzungen

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 die Rolle der Session die Berechtigung Anzeigen (show) besitzt.
Besitzereinschränkungen gelten nur für "API"-Entitäten, bei denen die Firma der Session als Besitzer eingetragen ist oder als Empfänger einer Firmenfreigaben gilt.

Übersicht aufrufen

Der Menüeintrag API-Manager befindet sich im Menüknoten Integration. Ein Klick öffnet die Übersicht für den Entitätstyp API (RestApiDefinition).

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

API-Instanz und API-Definition

Jede Konfiguration im API-Manager besteht aus zwei Ebenen.

API-Instanz (RestApiDefinition): Die äußere Hülle. Sie enthält allgemeine Metadaten wie Name, Beschreibung und Priorität. Die Instanz selbst definiert keine Endpunkte oder Tools.
API-Definition: Der eigentliche Schnittstelleninhalt. Er ist im Feld API (api) der Instanz eingebettet. Der Typ der API-Definition bestimmt, welche Endpunkte oder Tools bereitgestellt werden.

Folgende Typen stehen für die API-Definition zur Auswahl:

REST API (RestApi): Definiert Endpunkte für HTTP-Methoden und allgemeine REST-Zugriffe.
MCP-Server (McpRestApi): Definiert Tools für den KI-Zugriff per Model Context Protocol (MCP).

Die Erfassungsmaske ist für beide Typen identisch. Das Erscheinungsbild variiert je nach gewähltem Typ der API-Definition. Die Maske öffnet sich über den View-Namen de.lobster.scm.api::RestApiDefinition|detailsWindow.

HINWEIS Details zu den typspezifischen Tab-Reitern finden Sie unter REST API bzw. MCP-Server. Betroffen sind die Tab-Reiter API und ggf. Meta-Informationen.

Neue API anlegen

Klicken Sie in der Übersicht auf den Ribbon-Button Neu. Ein Kontextmenü erscheint. Wählen Sie dort den Typ der API-Definition aus.

WICHTIG Den Typ einer vorhandenen API-Definition können Sie nachträglich nicht ändern. Wählen Sie den Typ beim Erstellen sorgfältig aus. Er gilt für den gesamten Lebenszyklus der API-Instanz.

Der Ribbon-Button Neu erscheint nur, wenn die Rolle der Session die Berechtigung Erstellen (create) besitzt.
Die im Kontextmenü gewählte API-Definition bestimmt das Erscheinungsbild der geöffneten Erfassungsmaske.

Vorhandene API öffnen

Wählen Sie eine API-Instanz in der Übersicht aus. Öffnen Sie sie per Doppelklick oder über den Ribbon-Button Bearbeiten bzw. Details anzeigen.

Der Ribbon-Button Bearbeiten erscheint nur, wenn die Rolle der Session die Berechtigung Ändern (update) besitzt.
Besitzt die Rolle nur Anzeigen (show) oder Erstellen (create), erscheint stattdessen der Button Details anzeigen. Der Ribbon-Button Speichern ist in diesem Modus deaktiviert. Mit der Berechtigung Erstellen können Sie dennoch über den Ribbon-Button Kopieren eine neue API-Instanz anlegen und speichern.

Konfiguration

Die folgenden Abschnitte beschreiben die Konfigurationsmerkmale des Entitätstyps API (RestApiDefinition). Sie gelten unabhängig vom gewählten Typ der API-Definition. Jeder Abschnitt entspricht einem Tab-Reiter in der Erfassungsmaske.

Grundeinstellungen

Eigenschaft	Datenfeld	Datentyp	Beschreibung
Aktiviert	`enabled`	`Boolean`	Aktiviert (`true`) oder deaktiviert (`false`) die API-Instanz. Standardwert ist `false`. Neue API-Instanzen müssen explizit aktiviert werden. HINWEIS Änderungen am Aktivierungsstatus werden erst beim Speichern wirksam. Bei mehreren aktiven APIs mit überlappenden Endpunkt- oder Tool-Definitionen innerhalb derselben Basis-URI entscheidet die Priorität (s. unten), welche Instanz greift. Eine inaktive Instanz mit hoher Priorität blockiert keine eingehenden Aufrufe.
Besitzer	`ownerId`	`Long`	Als Besitzer wird automatisch die Firma der Session eingetragen, in deren Kontext die API-Instanz erstmalig gespeichert wird. Abweichungen lassen sich über ein Auswahlfeld/Combobox-Element konfigurieren. Besitzereinschränkungen und Firmenfreigaben haben keinen Einfluss auf den operativen Zugriff. Sie sind nur für die Konfigurationsverwaltung relevant.
Name	`name`	`String`	Jede API-Instanz benötigt einen Namen. Er muss nicht eindeutig sein. Er dient nur zur Orientierung in der Konfiguration und hat keine operative Relevanz.
Beschreibung	`description`	`String`	Optionales Freitextfeld für mehrzeilige Beschreibungen. Typisch für Konfigurationsdokumentation und Änderungshinweise. Kein Einfluss auf den Betrieb der Schnittstelle. HINWEIS Einer API-Instanz können zusätzlich Tags zugewiesen werden. Das erleichtert das Kategorisieren und den Transfer von Konfigurationen per Meta Exchange.
Priorität	`priority`	`Integer`	Ganzzahliger Wert (positiv oder negativ). Er greift, wenn mehrere API-Instanzen denselben Endpunkt oder dasselbe Tool innerhalb derselben Basis-URI definieren. Im Konfliktfall gilt ausschließlich die Definition aus der Instanz mit dem höchsten Prioritätswert. HINWEIS Inaktive API-Instanzen nehmen nicht an der Prioritätsauflösung teil. Eine inaktive Instanz mit hoher Priorität fängt keine Aufrufe ab.

Private Strukturen

Über den Tab-Reiter Private Strukturen legen Sie benutzerdefinierte Datenstrukturen an. Diese Strukturen sind über ihren Alias in der zugehörigen API-Instanz referenzierbar (s. Client Objekt-Struktur Referenz). Sie heißen privat, weil ihre Nutzung ausschließlich auf den Kontext dieser API-Instanz beschränkt ist.

Eine Datenstruktur definieren Sie, indem Sie alle Felder auflisten, die ein Client-Objekt enthalten kann oder muss.

Das folgende Beispiel zeigt zwei private Strukturen (Waypoint und Leg) im Kontext derselben API-Instanz:

Die private Struktur Waypoint definiert einen Wegpunkt entlang einer Flugverbindung.
Das Feld location erwartet einen String zur eindeutigen Kennzeichnung des Wegpunkts.
Das optionale Feld locationType nimmt einen weiteren String auf. Es gibt an, aus welchem Kontext der Wert in location stammt. Da die Checkbox Optional gesetzt ist, erscheint in der Feldliste ein ? als Suffix (locationType?). Ein Text Werte Validierer (Client-Objektstruktur) schränkt die zulässigen Werte auf ICAO und IATA ein.

Die private Struktur Leg demonstriert eine Wiederverwendung: Sie bezieht sich auf Waypoint als Datentyp für ihre eigenen Felder.
Konkret kombiniert Leg zwei oder drei Waypoint-Instanzen zu einer Flugverbindung: fromWaypoint, toWaypoint und optional viaWaypoint.

Im Workflow eines Endpunkts oder Tools können Sie die Prüfe Client-Objektstruktur (Regel) oder den Prüfe Client-Objektstruktur (Wertauflöser) verwenden, um Eingangsdaten gegen eine private Struktur zu validieren.

Alternativ können Sie eine private Struktur im Erzeuge Instanz mit Werten-Wertauflöser referenzieren. Das ermöglicht es, die Felder eines Client-Objekts für den Rückgabewert (Variable response) komfortabel zu befüllen:

HINWEIS In diesem Beispiel wird Waypoint nur als Client-Objektstruktur referenziert. Sie ermöglicht die Feldauswahl im Dropdown der Eigenschaft Eigenschaft. Der Text Werte Validierer (Client-Objektstruktur) für locationType wird dabei nicht geprüft. Diese Prüfung könnte ein nachgelagerter Prüfe Client-Objektstruktur (Wertauflöser) übernehmen.

Private Bausteine

Über den Tab-Reiter Private Bausteine definieren Sie Eigene Bausteine. Diese Bausteine sind privat, weil ihre Nutzung ausschließlich auf den Kontext dieser API-Instanz beschränkt ist.

Als private Bausteine können Ereignisaktionen, Wertauflöser oder Regeltypen definiert werden. Ihr Einsatz ist auf den Kontext der API-Instanz beschränkt.

Documentation Index