REST API

Dieser Artikel beschreibt die Klasse REST API (RestApi) im Entitätstyp API (RestApiDefinition). Über das Feld API (api) bindet die Klasse Endpunkte für eine benutzerdefinierte REST-API ein, die der Lobster Data Platform-Server bereitstellt.

Der Entitätstyp REST API Definition (RestApiDefinition) lässt sich alternativ für MCP Tools verwenden. Dazu kommt statt der Klasse REST API die Klasse MCP Server (McpRestApi) zum Einsatz. Details finden Sie unter MCP-Server.

Der gemeinsame Ausgangspunkt für die Verwaltung aller RestApiDefinition-Instanzen ist der Menüeintrag API-Manager. Dort finden Sie gemeinsame Details für alle Definitionen.

Die Erfassungsmaske (de.lobster.scm.api::RestApiDefinition|detailsWindow) enthält zwei Tab-Reiter mit spezifischen Inhalten für die Klasse REST API:

• API (verfügbar für REST API und MCP Server)

• Meta-Informationen (nur für REST API)

Weitere Themen

Wegen des Umfangs verteilen sich Details auf folgende Unter-Topics:

• REST API: URI und URI-Parameter: URI-Format, URI-Parameter mit Trennzeichen, dynamische Pfade über reguläre Ausdrücke.

• REST API: Eingabetyp „Client-Objekt" (ASObject): Client-Objektstruktur, Aerodrome-Beispiel, HTML-Formulardaten.

• REST API: Erweiterte Endpunkt-Einstellungen: Anonymer Zugriff, Sunset, Richtlinien-Einstellungen, OpenAPI-Fehlercodes.

• REST API: Aktionsblock-Kontext: Deklarierte Variablen, Rückgabewert, anonymer vs. autorisierter Zugriff.

• REST API: Meta-Informationen und Versionierung: RestApiMetadata-Struktur, Versionierungsansätze.

Tab-Reiter „API"

Kopfbereich

Der Kopfbereich enthält Elemente, die nicht an einen bestimmten Endpunkt gebunden sind.

Im Textfeld für die Eigenschaft Basis-URI (baseUri) geben Sie die gemeinsame Basis-Adresse für alle Endpunkte der REST-API-Instanz an.

Die Verknüpfung OpenAPI-Dokumentation anzeigen öffnet einen neuen Browser-Tab. Dort sehen Sie eine automatisch generierte Swagger-Dokumentation für alle Endpunkt-Konfigurationen unter dieser Basis-URI.

Die OpenAPI-Dokumentation berücksichtigt nur den gespeicherten Stand aller aktiven REST-API-Definitionen unter derselben Basis-URI. Endpunkt-Definitionen aus inaktiven REST-API-Definitionen erscheinen nicht.

Stellen mehrere aktive REST-API-Definitionen Endpunkt-Definitionen für dieselbe Endpunkt-URI (uri) bereit, entscheidet deren Prioritätswert. Details dazu finden Sie unter API-Manager. Die OpenAPI-Dokumentation zeigt nur den effektiv wirksamen Endpunkt. Welche REST-API-Definition diesen Endpunkt liefert, ist in der Dokumentation nicht erkennbar.

Endpunkte-Liste

Unterhalb des Kopfbereichs zeigt ein Datengrid-Element in der linken Hälfte des Detailbereichs alle angelegten Endpunkte.

• Für eine neue REST-API ist die Liste leer.

• Über die Buttons rechts neben der Liste fügen Sie einen Endpunkt hinzu () oder entfernen den angezeigten Endpunkt ().

• Per Klick in eine Zeile wählen Sie einen Listeneintrag aus. Der Detailbereich zeigt dann die zugehörigen Daten.

• Beim ersten Öffnen des Tab-Reiters ist kein Eintrag ausgewählt. Der Detailbereich bleibt leer.

• Ein Klick auf einen bereits ausgewählten Eintrag wählt diesen wieder ab. Der Detailbereich zeigt dann keine Daten mehr.

• Solange die Liste den Fokus hat, navigieren Sie auch über die Cursor-Tasten (↑↓). Der ausgewählte Eintrag erscheint in der Primärfarbe. Details zur Primärfarbe finden Sie unter Styles.

Die Liste lässt sich filtern und sortieren. Diese Einstellungen gelten nur, solange die Erfassungsmaske geöffnet ist. Die Plattform speichert sie nicht.

Das Kontextmenü oben rechts in der Liste bietet folgende Funktionen für Datengrids (Details: Datengrid):

• Spaltensichtbarkeit ändern

• Listeneinstellungen zurücksetzen

• Liste exportieren

 HINWEIS Die Liste speichert keine Spalten- und Filtereinstellungen. Das Zurücksetzen ist deshalb funktional ohne Wirkung.

Endpunkt-Detailbereich

Rechts neben der Endpunkte-Liste zeigt der Detailbereich die Daten des ausgewählten Endpunkts.

Der Kopf des Detailbereichs enthält die bereits erwähnten Buttons zum Hinzufügen und Entfernen sowie Formularelemente für den direkten Zugriff auf Eigenschaften (Methode, URI) und einen Button Erweiterte Einstellungen für den indirekten Zugriff über einen Dialog.

 HINWEIS Abhängig von der getroffenen Auswahl erscheinen oder entfallen Formularelemente. Beim Entfall gehen eingegebene Daten verloren.

Das Auswahlfeld/Combobox-Element für den Eingabetyp erscheint nur abhängig von der gewählten Methode. Für die HTTP-Methoden GET und DELETE erwartet die Plattform keinen Eingabewert. Die Eingabetyp-Auswahl entfällt dann.

Die Checkbox Ist Liste von erscheint, sobald Sie einen Eingabetyp gewählt haben. Ist die Checkbox aktiv, erwartet die Plattform als Eingabewert eine Liste von Einträgen des gewählten Typs.

Für den Eingabetyp „Client-Objekt" (ASObject) erscheint zusätzlich der Button Client-Objektstruktur. Details dazu finden Sie unter REST API: Eingabetyp „Client-Objekt" (ASObject).

Der Button Erweiterte Einstellungen öffnet einen Dialog mit weiteren Einstellungen. Details finden Sie unter REST API: Erweiterte Endpunkt-Einstellungen.

Über den Button Zuweisen binden Sie optional Zuordnungskriterien an den Endpunkt. Damit steuern Sie die Verfügbarkeit über Bedingungen wie Rollenregel oder Firmenregel. Details finden Sie unter Zugriffskontrolle für APIs.

Das Hauptfenster des Detailbereichs ist vertikal in zwei Bereiche geteilt:

• Links zeigt eine Baumansicht die Datenstruktur des ausgewählten REST-API-Endpunkt-Objekts (RestApiEndpoint). Zusätzlich erscheint ein Knoten Deklarierte Variablen. Details dazu finden Sie unter REST API: Aktionsblock-Kontext.

• Rechts daneben bauen Sie aus Ereignisaktionen einen Aktionsblock für die Ereignisbehandlung des Endpunkts auf. Details unter Konfiguration von Ereignisbehandlungen.

 HINWEIS An der Grenze zwischen Kopf und Hauptfenster zeigt die Plattform die Endpunkt-URL nach folgendem Schema an: <platform-url>/api/<baseUri>/<uri>

• <platform-url>: URL der aktuellen Client-Sitzung.

• <baseUri>: Teilzeichenfolge aus der Eigenschaft Basis-URI (baseUri) der Klasse REST API. Gilt einheitlich für alle Endpunkte der REST-API.

• <uri>: Teilzeichenfolge aus der Eigenschaft URI (uri) der Klasse REST-API-Endpunkt. Spezifisch für den jeweiligen Endpunkt.

 ACHTUNG  Vermeiden Sie, dass in der Gesamt-URI direkt nach dem vordefinierten Literal /api/ die Zeichenfolge mcp/ folgt. Sonst kann es zu Konflikten zwischen den Definitionen für MCP-Server und REST API kommen.

Methode (method)

Die folgenden HTTP-Methoden stehen zur Verfügung:

URI (uri)

Die URI-Eigenschaft identifiziert den Endpunkt über eine statische Zeichenfolge. Optional kann diese Zeichenfolge ein durch Schrägstriche (/) gegliederter Pfad sein. Variable Bestandteile geben Sie als URI-Parameter an.

Details zu URI-Parametern, Trennzeichen, dynamischen Pfaden und Beispielen finden Sie unter REST API: URI und URI-Parameter.

Eingabetyp (inputValueType, isCollectionOf, clientStructure)

Das Auswahlfeld/Combobox-Element für den Eingabetyp (inputValueType) erscheint nur, wenn die Methode (method) einen Eingabewert benötigt. Das betrifft die Methoden POST, PUT und PATCH.

Das Dropdown enthält Datentypen verschiedener Kategorien: einfache Werte wie Boolean, komplexe Datenobjekte wie DateRange, konkrete Entitätstypen, übergeordnete Klassen, Schnittstellen.

Die Auswahl ist optional. Ohne Auswahl verwendet die Plattform den unspezifischen Datentyp Objekt (Object).

• Die Checkbox Ist Liste von (isCollectionOf) aktivieren Sie, wenn als Eingabewert eine Liste von Einträgen des gewählten Eingabetyps erlaubt sein soll.

• Für eine Liste von Einträgen mit beliebigem Eingabetyp wählen Sie den Typ Objekt (Object) und aktivieren Ist Liste von.

• Alternativ wählen Sie den Typ Liste (java.util.List) oder Eindeutige Liste (java.util.Set) ohne Ist Liste von.

• Bei Set müssen die Einträge nicht eindeutig sein. Allerdings entfernt die Plattform Duplikate im Aktionsblock. Die Reihenfolge der Werte kann vom Eingabewert abweichen.

• Wenn der Eingabetyp kein konkreter Typ ist, sondern zum Beispiel eine Schnittstelle wie Schnittstelle > Benutzer (IUser), prüft die Plattform, ob im Response Body eine kompatible Klasse vorliegt.

• Ist die im Response Body deklarierte Klasse (class) nicht mit dem Eingabetyp kompatibel, antwortet die Plattform mit HTTP-Fehler 404 Error: Not Found.

Besonderer Eingabetyp: „Inhalt" (Content)

Wenn Sie als Eingabetyp den Typ Inhalt (Content) wählen, deserialisiert die Plattform den Eingabewert nicht automatisch. Stattdessen erzeugt sie ein Datenobjekt vom Typ Content.

• Das body-Feld enthält die Nutzlast aus dem Request.

• Das mediaType-Feld erhält den Wert des Content-Type-Headers.

• Das name-Feld bleibt leer.

So verarbeiten Sie zum Beispiel eine Binärdatei oder parsen benutzerdefiniertes XML im Aktionsblock. Siehe XML Parsen.

Besonderer Eingabetyp: „Client-Objekt" (ASObject)

Wenn Sie als Eingabetyp den Typ Client-Objekt (ASObject) wählen, definieren Sie über die Client-Objektstruktur eine Client Objekt-Struktur Referenz im Feld clientStructure.

Details, Beispiele und die Behandlung von HTML-Formulardaten finden Sie unter REST API: Eingabetyp „Client-Objekt" (ASObject).