REST API

Hintergrund: “REST API Definition” vs. “REST API”

Die nachfolgenden Informationen betreffen die Klasse “REST API” (RestApi), die über das Feld “API” (api) in den Entitätstyp “REST API Definition” (RestApiDefinition) eingebunden wird, um über den Lobster Data Platform-Server Endpunkte (Endpoints) für eine benutzerdefinierte REST-API bereitzustellen. Derselbe Entitätstyp “REST API Definition” (RestApiDefinition) kann alternativ auch verwendet werden, um MCP Tools (s. MCP-Server) zu definieren, wenn stattdessen die Klasse “MCP Server” (McpRestApi) verwendet wird.

• Der gemeinsame Ausgangspunkt für die Verwaltung von jeglichen Instanzen des Entitätstyps “REST API Definition” (RestApiDefinition) ist per Standard der Menüeintrag API-Manager (gemeinsame Details s. dort).

• Die nachfolgende Dokumentation behandelt spezifische Details für die Klasse “REST API” (RestApi).

  • Die Benutzeroberfläche ermöglicht den Zugriff auf diese Details im Kontext der Erfassungsmaske für den Entitätstyp “REST API Definition” (RestApiDefinition), die ausgehend vom API-Manager geöffnet werden kann.

  • Innerhalb der gemeinsamen Erfassungsmaske (de.lobster.scm.api::RestApiDefinition|detailsWindow) enthalten folgende Tab-Reiter spezifische Inhalte für die Klasse “REST API” (RestApi):

    • Tab-Reiter “API” (verfügbar für “REST API” und “MCP Server”)

    • Tab-Reiter “Metainformationen” (exklusiv verfügbar für “REST API”)

Tab-Reiter “API”

Kopfbereich

Der Kopfbereich beinhaltet Elemente, die nicht an eine spezifische Endpunkt-Definition gebunden sind:

• Im Textfeld für die Eigenschaft Basis-URI (baseUri) muss die gemeinsame “Basis-Adresse” für die im Kontext der “REST API”-Instanz definierten Endpunkte angegeben werden.

• Die Verknüpfung OpenAPI Dokumentation anzeigen öffnet einen neuen Browser-Tab mit einer automatisch generierten Swagger-Dokumentation für alle effektiven Endpunkt-Konfigurationen für die per Basis-URI identifizierte API.

  • Ausschlaggebend für die OpenAPI-Dokumentation ist der zu diesem Zeitpunkt persistierte (gespeicherte) Stand aller aktiven “REST API Definitionen”, die sich auf dieselbe Basis-URI beziehen.

  • Endpunkt-Definitionen aus inaktiven “REST API Definitionen” werden nicht berücksichtigt.

  • Stellen mehrere aktive “REST API Definitionen” Endpunkt-Definitionen für dieselbe Endpunkt-”URI” (uri) bereit, bestimmt deren Prioritätswert (s. API-Manager) den Ausschlag für den Vorrang. Die Dokumentation beschreibt nur den jeweils effektiv wirksamen Endpunkt. Ein unmittelbarer Hinweis zur “REST API Definition”, die den effektiv wirksamen Endpunkt definiert, ist in der Dokumentation nicht nachvollziehbar.

Endpunkte-Liste

Unterhalb des Kopfbereichs listet in der linken Hälfte des Detailbereichs ein Datengrid-Element alle innerhalb der “REST API Definition” angelegten Endpunkte (Endpoints) auf.

• Für eine neu angelegte “REST API” ist diese Liste leer. Über die beiden Buttons oben links im Detailbereich rechts von der Liste kann dieser ein Eintrag (Endpunkt) hinzugefügt () oder der im Detailbereich angezeigte Eintrag entfernt () werden.

• Liegen bereits Listeneinträge für Endpunkte vor, dann kann per Klick in die Listenzeile ein einzelner Listeneintrag ausgewählt werden, um die zugehörigen Daten im Detailbereich anzuzeigen.

• Beim ersten Betreten des Tab-Reiters ist initial kein Eintrag ausgewählt. der Detailbereich zeigt dann keine Detaildaten an.

• Ein Klick in die Listenzeile für einen bereits ausgewählten Eintrag wählt diesen wieder ab, sodass der Detailbereich keine konkreten Daten mehr anzeigt.

• Die Auswahl des anzuzeigenden Listeneintrags kann auch über Cursor-Tasten (↑↓) gesteuert werden, solange die Liste den Fokus hat. Dies ist daran erkennbar, dass der ausgewählte Listeneintrag in der Primärfarbe (s. Styles) hervorgehoben wird.

Die Liste kann gefiltert und sortiert werden. Die zugehörigen Einstellungen gelten allerdings nur bis die Erfassungsmaske geschlossen wird. Sie werden nicht als Benutzer-Einstellungen gespeichert.

Das Kontextmenü (rechts oben in der Liste) unterstützt folgende Funktionalitäten für Datengrids (s. Datengrid):

• Sichtbarkeit von Spalten ändern (Einstellungen werden nicht gespeichert)

• Listeneinstellungen zurücksetzen (wirkungslos, weil Einstellungen nicht gespeichert werden)

• Liste exportieren

Endpunkt-Detailbereich

Der Detailbereich für Endpunkte (rechts neben der Endpunkte-Liste) bietet Zugriff auf Detaildaten für den in der Liste ausgewählten Endpunkt:

• Der Kopf des Detailbereichs beherbergt neben den bereits erwähnten Buttons zum Hinzufügen () oder Entfernen () von Endpunkten Formularelemente für den direkten (Methode, Uri, etc.) oder indirekten (Button Erweiterte Einstellungen) Zugriff auf Eigenschaften des Endpunkts.
   HINWEIS  Abhängig von bereits betroffenen Auswahl können in diesem Bereich Formularelemente erscheinen oder entfallen. Beim Entfall gehen ggf. eingegebene Daten dabei 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 wird kein Eingabewert erwartet. Dann ist eine Auswahl für den Eingabetyp nicht relevant.

  • Für den Eingabetyp “Client-Objekt” (ASObject) erscheint zuätzlich der Button Client-Objektstruktur, über den eine Eigene Client-Objektstruktur oder eine im Kontext der “REST API Definition” (RestApiDefinition) angelegte “Private Struktur” (s. API-Manager) referenziert oder eine “Neue Client-Objektstruktur” für den Eingabetyp lokal angelegt werden kann.
    

• Das Hauptfenster des Detailbereichs ist vertikal in zwei Bereiche geteilt:

  • Links visualisiert eine Baumansicht die Datenstruktur für das ausgewählte “REST-API-Endpunkt” (RestApiEndpoint)-Datenobjekt. Zusätzlich erscheint ein Knoten für Deklarierte Variablen (Details s. unten), mit denen im Kontext des Aktionsblocks gearbeitet werden kann.

  • Rechts davon kann aus Ereignisaktionen ein Aktionsblock für die Ereignisbehandlung für den Endpunkt aufgebaut werden (s. Konfiguration von Ereignisbehandlungen).
    

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

• <platform-url> ist dabei die URL unter die die aktuelle Client-Sitzung aufgebaut wurde.

• <baseUri> ist eine Teilzeichenfolge der Gesamt-URL, der durch die Eigenschaft “Basis-URI” (baseUri) der Klasse “REST API” (RestApi) einheitlich für alle zugehörigen Endpunkte definiert werden kann.

• <uri> ist eine Teilzeichenfolge der Gesamt-URL, die über die Eigenschaft “URI” (uri) innerhalb der Klasse “REST-API-Endpunkt” (RestApiEndpoint) spezifisch für den Endpunkt definiert werden kann.

 ACHTUNG  Zuweisungen für <baseUri> (und ggf. <uri>) sollten unbedingt so getroffen werden, dass innerhalb der Gesamt-URI auf das vordefinierte Literal /api/ nicht direkt die Zeichenfolge mcp/ folgt. Anderenfalls kann es zu Konflikten bei der Adressierung zwischen den Definitionen für MCP-Server und REST API kommen.

Methode (method)

Es stehen folgende HTTP Methoden zu Verfügung:

URI (uri)

Im einfachsten Fall identifiziert die “URI”-Eigenschaft nur den Endpunkt durch eine statische Zeichenfolge, bei der es sich optional um einen durch Schrägstriche (/) gegliederten Pfad handeln kann.

Allerdings können auch variable Bestandteile - repräsentiert als URI-Parameter - deklariert werden, um Abschnitte der zur Laufzeit adressierten URI auf Variablen für den Aktionsblock abzubilden.

Beispiel:

Das Löschen einer Entität eines bestimmten Typs soll über einen Endpunkt (./demo/deleteItem/{id}) mit der DELETE-Methode ermöglicht werden, wobei ein URI-Parameter ({id} - Details s. u.) die zu löschende Entität über deren interne “ID” (id) identifizieren soll.

 HINWEIS  Ein URI-Parameter liefert primär immer einen Textwert (String). Im Aktionsblock können daher explizite Typumwandlungen erforderlich sein, wie das folgende Beispiel verdeutlicht.

URI-Parameter

Der für die Eigenschaft “URI” (uri) angegebene Textwert kann neben Klartextzeichen auch URI-Parameter im Format {<variable>} enthalten. Zur Laufzeit werden dann die korrespondierenden Teilzeichenfolgen aus der angegebenen Aufrufadresse als Textwerte auf Variablen (s. Variable) abgebildet, auf die im Aktionsblock zugegriffen werden kann.
 WICHTIG  Die zur Laufzeit zugewiesene Zeichenfolge sollte URL Enkodierung verwenden, um HTTP-relevante Sonderzeichen zu maskieren, z. B. %20 für das Leerzeichen, %2F für einen Schrägstrich (/) oder %3F für das Fragezeichen (?).

Die Zeichenfolge für die Eigenschaft “URI” (uri) kann mehrere URI-Parameter beinhalten, zwischen deren Definition je ein geeignetes Trennzeichen einzusetzen ist. Das Trennzeichen darf nicht (unmaskiert) in den zur Laufzeit bereitgestellten Strings enthalten sein.

 WICHTIG  Sämtlich URI-Parameter werden per Definition als Pflichtangaben behandelt. Eine leere Zeichenfolge ("") kann nicht als %00 zugewiesen werden. Dies schränkt die Einsatzmöglichkeiten für den Standardwert-Wertauflöser ein.

 HINWEIS  Falls ein HTTP-relevantes Sonderzeichen als Trennzeichen verwendet wird, muss auch dieses zur Laufzeit per URL Enkodierung maskiert werden, z. B. %23 statt dem Hash-Symbol (#).

---

Beispiel:

• Als Basis-URI für eine API-Definition (baseUri) ist der Text demo angegeben.

• Die API-Definition stellt einen Endpunkt bereit, der über die GET-Methode einen Ausgabetext liefern soll, der die Systemzeit mit per URI wählbarer Zeitzone und Formatierung ausgeben soll.

  • Als Zeichenfolge für die “URI” (uri) wird folgender Text angegeben: getTime/{zone}|{format}

• Zur Laufzeit kann der Endpunkt wie folgt adressiert werden: https://████████████/api/demo/getTime/Europe%2FAthens|EEEE%20HH:mm%20z

  • Der Text zwischen getTime/ und dem als Trennzeichen verwendeten Pipe-Symbol (|) erscheint dekodiert als Textwert Europe/Athens für die Variable zone.

  • Der Text nach dem Pipe-Symbol (|) erscheint als Textwert EEEE HH:mm z für die Variable format.

  • Im Aktionsblock kann anhand dieser Text-Parameter der gewünschte Ausgabetext (z. B. Mittwoch 19:40 Europe/Athens) erzeugt werden.

 ANMERKUNG  Wie das Beispiel zeigt, kann das Datumsformat lokalisierungspflichtige Bestandteile (hier: den Volltext für den Wochentag mit dem Pattern EEEE) enthalten. Um für diesen Fall die Ausgabesprache optional wählbar zu machen, könnte zusätzlich ein Abfrage-Parameter locale einbezogen werden, mit dem der Aufruf z. B. so formuliert werden könnte: https://████████████/api/demo/getTime/Europe%2FAthens|EEEE%20HH:mm%20z?locale=fr

Der Zugriff auf den Parameter locale im Aktionsblock erfolgt dann über die systemseitig befüllte Variable queryParameters per Map-Wert-Wertauflöser mit dem Schlüssel locale.

• Der gewünschte Ausgabetext für die angeforderte Sprache “Französisch” (fr) lautet dann z. B.: mercredi 19:40 Europe/Athens

---

Am Ende der per Eigenschaft “URI” (uri) definierten Zeichenfolge kann ein dynamischer Pfad über einen URI-Parameter mit folgendem Schema angegeben werden: {<variable>: <regExp>}

• Falls der korrespondierende Abschnitt der zur Laufzeit adressierten URI vollständig mit dem angegebenen Regulären Ausdruck (<regExp>) übereinstimmt, wird er in die Variable (<variable>) übernommen.

• Entspricht der korrespondierende Abschnitt der zur Laufzeit adressierten URI dagegen nicht dem angegebenen Regulären Ausdruck (<regExp>), scheitert der Aufruf mit Fehler (“404 - NOT FOUND“).

Beispiel:

• Als Basis-URI für eine API-Definition (baseUri) ist der Text demo angegeben.

• Die API-Definition stellt einen Endpunkt bereit, der über die GET-Methode Daten zu einem bestimmten “Künstler” in einer Mediendatenbank ausgeben soll.

  • Als Zeichenfolge für die “URI” (uri) wird zunächst folgender Text angegeben: getArtist/{name: .+}

    • Der Reguläre Ausdruck .+ akzeptiert dabei beliebige Zeichen (z. B. U2, UB40, AC/DC, Van%20Halen, Primus, MEGADETH) solange mindestens ein Zeichen bereitgestellt wird.

    • Würde stattdessen der Reguläre Ausdruck [A-Z]+[0-9]* vordefiniert, dann wären aus den obigen Beispielen nur noch die “Künstler” U2, UB40 und MEGADETH “adressierbar”.

    • Mit dem Regulären Ausdruck [a-zA-Z/]|%20|%2F)+[0-9]* wären wieder alle genannten “Künstler” kompatibel. Für AC/DC würde dabei auch die eigentlich zu bevorzugende Schreibweise mit URL Enkodierung (AC%2FDC) unterstützt.

Eingabetyp (inputValueType, isCollectionOf, clientStructure)

Das Auswahlfeld/Combobox-Element für den “Eingabetyp” (inputValueType) erscheint nur, wenn eine “Methode” (method) ausgewählt ist, die einen Eingabewert verwendet. Dies betrifft die Methoden POST, PUT und PATCH, die typischerweise auf das Erstellen oder  Aktualisieren von Ressourcen abzielen (s. Tabelle im Abschnitt “Methode (method)”).

Im Dropdown stehen Datentypen unterschiedlicher Kategorien auswählbar (simple Werte wie Boolean,  komplexe Datenobjekte wie DateRange, konkrete Entitätstypen, übergeordnete Klassen, Schnittstellen, usw.).

Die Auswahl für den “Eingabetyp” ist optional. Ohne eine Auswahl wird formal der komplett unspezifische Datentyp “Objekt” (Object) herangezogen.

• Die Checkbox “Ist Liste von” (isCollectionOf) kann gesetzt werden, wenn als Eingabewert eine “Liste” ([]) von Einträgen mit einem zusätzlich ausgewählten “Eingabetyp” zulässig sein soll.

  • Eine “Liste” von Einträgen mit einem beliebigen “Eingabetyp” kann durch Auswahl des Typs '“Objekt” (Object) in Verbindung mit “Ist Liste von” (isCollectionOf) als Eingabewert definiert werden.

  • Alternativ kann der Typ “Liste” (java.util.List) oder “Eindeutige Liste” (java.util.Set) angegeben werden ohne die Option “Ist Liste von” (isCollectionOf) auszuwählen.

    • Die bereitgestellten Einträge müssen im zweiten Fall (Set) nicht eindeutig sein. Allerdings entfallen im Aktionsblock Duplikate und die Reihenfolge der Werte kann von Eingabewert abweichen.

• Sofern es sich beim “Eingabetyp” nicht um einen konkreten Typ, sondern z. B. um eine Schnittstelle wie “Schnittstelle > Benutzer” (IUser) handelt, wird geprüft, ob im Response Body eine kompatible Klasse vorliegt.

• Ist die im Response Body deklarierte Klasse (class) nicht mit dem als “Eingabetyp” ausgewählten Typ kompatibel, wird ein Fehler (404 Error: Not Found) ausgegeben.

Besonderer Eingabetyp “Inhalt” (Content)

Wenn als “Eingabetyp” der Typ “Inhalt” (Content) deklariert ist, dann erfolgt keine automatische Deserialisierung des beim Aufruf bereitgestellten Eingabewerts. Stattdessen wird ein Datenobjekt vom Typ “Inhalt” (Content) erzeugt, dem die “Nutzlast” aus dem Request im body-Feld zugeordnet wird. Das mediaType-Feld wird analog zum Content-Type Header gesetzt. Das name-Feld bleibt leer.

So kann z. B. eine Binärdatei verarbeitet oder ein benutzerdefiniertes XML im Aktionsblock geparst werden (s. XML Parsen).

Besonderer Eingabetyp: “Client-Objekt” (ASObject)

Wenn als “Eingabetyp” der Typ “Client-Objekt” (ASObject) ausgewählt ist, erscheint rechts neben dem Auswahlfeld/Combobox-Element ein Button mit der Beschriftung “Client-Objektstruktur”, über den eine Client Objekt-Struktur Referenz (im Feld clientStructure) definiert werden kann. Der Klick auf den Button öffnet ein Popover-Element, mit dem eine vorhandene Definition für eine private oder öffentliche Client-Objekt-Struktur ausgewählt oder eine lokale (direkt im Popover) erstellt werden kann:

 HINWEIS  Ignoriere zusätzliche Eigenschaften bezieht sich nur auf die Akzeptanz eines Client-Objekts als Eingabetyp für den Endpunkt. Zusätzlichen Felder und deren Werte werden nicht etwa aus dem Datenobjekt entfernt. Im Aktionsblock kann auf diese Felder also sehr wohl zugegriffen werden. Für den Zugriff über den Objekt-Feld-Wertauflöser muss dabei allerdings ein konkreter Feldname (hier: designation) als Freitext angegeben werden. Bei Bedarf könnten unterschiedliche Feldnamen durch das Verketten von mehreren Standardwert-Wertauflösern “durchprobiert” werden, bis einer von mehreren Feldnamen einen Wert liefert. Alternativ kann der Typ “Client-Objekt” auch als Map behandelt werden. Der Alle Map-Schlüssel-Wertauflöser ermöglicht die systematische Auswertung aller vorhandener Feldnamen.

Eingabetyp: “Client-Objekt” (ASObject) für HTML-Formulardaten

Ein Requests der über den Content-Type Header das Format application/x-www-form-urlencoded liefert typischerweise Daten aus einem HTTP-Formular als Verkettung von Schlüssel-Wert-Paaren in einem URL-codierten String.

Diese Daten können mit dem Eingabetyp Client-Objekt verarbeitet werden. Die folgende Tabelle verdeutlicht die Interpretation der Syntax an Beispielen:

{
    "fname": "John",
    "lname":
}

{
    "fname": ["John", "Agent"],
    "lname": ["Doe", "Smith"]
}

{
    "fname": ["John"],
    "lname": ["Doe"]
}

Endpunkt - Erweiterte Einstellungen

Allgemeine erweiterte Einstellungen (oberer Bereich im Dialog)

Ein Klick auf den Button “Erweiterte Einstellungen” öffnet einen modalen Dialog, der Zugriff auf weitere Einstellmöglichkeiten für den Endpunkt eröffnet:

• Die Checkbox “Eingabe muss gefüllt sein” (inputMandatory) entscheidet darüber, ob ein geeigneter Eingabewert verpflichtend bereitgestellt werden muss oder als optional (Standard) behandelt wird.

• Die Checkbox “Anonymer Zugriff” (allowAnonymousAccess) entscheidet darüber, ob der Endpunkt für “Anonymen Zugriff” freigegeben werden soll oder nicht (Standard).
   ACHTUNG  Die Freigabe eines Endpunkts für anonymen Zugriff sollte v. a. in einem öffentlich zugänglichen Produktivsystem nur in absoluten Ausnahmenfällen zugelassen werden. Das unbedachte oder missbräuchliche Auslösen von Operationen im Aktionsblock durch “anonyme Aufrufer” kann abhängig vom konfigurierten Workflow weitreichende Konsequenzen haben und sowohl die Datensicherheit als auch die Verfügbarkeit der Lobster Data Platform insgesamt gefährden (s. Abschnitt “Anonymer vs. autorisierter Zugriff“).

• Die Checkbox “Ist veraltet” (isDeprecated) kann gesetzt werden, um einen Endpunkt als veraltet zu deklarieren, um ihn nach einer Karenzzeit kontrolliert außer Betrieb nehmen zu können.

  • Sobald die Option gesetzt wird, erscheint ein Datum/Uhrzeit-Element, indem der Sunset - also der Zeitpunkt, bis zu dem der veraltete Endpunkt noch verfügbar sein soll - minutengenau angegeben werden kann.

    • Bis zum Sunset-Zeitpunkt bleibt der Endpunkt in Betrieb. Allerdings wird er in der “OpenAPI-Dokumentation” bereits als “veraltet” gekennzeichnet.

    • Ein Aufruf nach dem Sunset-Zeitpunkt erzeugt eine spezifische Fehlermeldung (410 Error: Gone).

• Das Textfeld “Beschreibung” (description) kann optional mit informativem Klartext befüllt werden, der typischerweise die Endpunkt-Konfiguration dokumentiert.

Richtlinien-Einstellungen (policySettings)

Der Tab-Reiter “Richtlinien-Einstellungen” im unteren Bereich des Dialogs für “Erweiterte Einstellungen” ermöglicht den Zugriff auf Richtlinien für den Zugriff auf den Endpunkt, die das Listenfeld policySettings der Endpunkt-Definition beinhaltet.

Wozu dienen Richtlinien-Einstellungen?

Der Zweck von Richtlinien-Einstellungen ist die Definition von Obergrenzen für die Zugriffsfrequenz für einen bestimmten Endpunkt zur Laufzeit.

Derselbe Endpunkt kann dabei unterschiedliche “Richtlinien-Einstellungen” parallel verwenden, um eine zulässige Charakteristik für die Häufigkeit von Zugriffen möglichst flexibel modellieren zu können.

Jede einzelne Richtlinie bezieht sich dabei auf ein bestimmtes Zeitfenster, für das eine maximale Anzahl von Zugriffen auf den Endpunkt festgelegt wird.

Durch eine Kombination von zwei solcher Richtlinien könnte z. B. folgende Charakteristik für eine Zugriffsbeschränkung formuliert werden:

• Ein API-Endpunkt soll innerhalb von 24 Stunden nicht öfter als 500 Mal adressiert werden dürfen.

• Der Zeitabstand zwischen zwei Aufrufen soll mindestens 30 Sekunden betragen.

Sobald eine dieser beiden Richtlinien verletzt wird, gibt der “überzählige” Aufrufversuch einen spezifischen Fehler (429 Error: Too Many Requests) im Response body zurück.

 HINWEIS  Details zur verletzten Richtlinie sind in diesem Fall den Response headers zu entnehmen.

Im Dialog erscheinen konfigurierte “Richtlinien-Einstellungen” in einem Datengrid. Oberhalb befindet sich ein Detailbereich, der den Zugriff auf Details einer ausgewählten Instanz über Formularelemente ermöglicht.

• Per Standard sind keine “Richtlinien-Einstellungen” definiert.

• Der Button “Neu” (mit dem Symbol ) fügt einen Listeneintrag hinzu.

• Der Button “Entfernen” (mit dem Symbol ) entfernen den im Detailbereich angezeigten Listeneintrag.

Jede Richtlinie wird dabei durch einen Listeneintrag mit dem Typ “Richtlinien-Einstellungen” (PolicySettings) mit den folgenden Eigenschaften repräsentiert:

• Das Auswahlfeld/Combobox “Richtlinie” (policy) ermöglicht eine Einfachauswahl aus einer Aufzählung (Klasse Policy) zur Klassifikation der Richtlininie.

• Das Feld “Max. Zugriffe” (maxRequests) definiert eine Obergrenze für die zulässige Anzahl von Zugriffen auf den Endpunkt in einem in Millisekunden einstellbaren Zeitfenster (s. nächste Eigenschaft).

• Das Feld “Zeitfenster in Millisek.” (timeFrameMs) definiert den Referenzzeitraum für die über die Eigenschaft “Max. Zugriffe” (maxRequests) definierte Obergrenze für die Zugriffsfrequenz.

 HINWEIS  Alle Angaben werden als Pflichtfelder behandelt. Jede hinzugefügte Richtlinie muss also vollständig parametriert werden.

OpenAPI-Fehler-Codes

Der Tab-Reiter “OpenAPI-Fehler-Codes” im unteren Bereich des Dialogs für “Erweiterte Einstellungen” ermöglicht den Zugriff auf “OpenAPI Fehler-Codes”, die im Listenfeld statusCodes der Endpunkt-Definition verwaltet werden.

Diese Auflistung von Fehlern reichert die “OpenAPI Dokumentation” (s. o.) mit alternativen Rückgabewerten neben dem regulären Response (s. u.) per Status Code 200 für den betreffenden Endpunkt an.

 WICHTIG  Änderungen im Tab-Reiters “OpenAPI-Fehler-Codes” müssen gespeichert werden, damit sie in der “OpenAPI Dokumentation” erscheinen.

Die Einträge in dieser Liste können komplett manuell über die Benutzeroberfläche angelegt und verwaltet werden.

Bei einem Klick auf den Button Profile nach geworfenen HTTP-Fehlern durchsuchen (ganz oben im Tab-Reiter) werden alle im Aktionsblock adressierten Profile nach Instanzen der Funktion throw http exception() durchsucht, die zum “Werfen” — also dem gezielten Auslösen — von Fehlern dient. Sofern die Suche in Funktionsaufrufen Status Codes vorfindet, die in der statusCodes-Liste des Endpunkts noch nicht enthalten sind, werden diese an die bestehende Liste angehängt.

 HINWEIS  Das Durchsuchen der Profile nach geworfenen HTTP-Fehlern bewirkt keine Aktualisierung, falls bereits ein Listeneintrag mit dem betreffenden Status Code existiert.

• Falls nach einer Änderung im Profil geänderter Content für einen bereits gelisteten Fehlercode erwartet wird, gelangt diese Information per Klick auf den Button Profile nach geworfenen HTTP-Fehlern durchsuchen nur in die Liste, wenn der veraltete Eintrag vorab manuell entfernt wird.

• Bei der Suche nicht (mehr) gefundene Fehlercodes werden nicht automatisch aus der Liste entfernt. Sie werden auch nicht als verwaist gekennzeichnet.

 WICHTIG  Werte für Status Codes (in der Spalte HTTP-Antwortcodes) sollten innerhalb der Liste strikt eindeutig vergeben werden, um “Verwirrung” (bzgl. OpenAPI) zu vermeiden.

• Als HTTP Response Status Codes sind definitionsgemäß positive Ganzzahlen zwischen 100 und 599 zu erwarten.

• Für Client Errors sind positive Ganzzahlen zwischen 400 und 499 vorgesehen.

• Interaktiv können über die Benutzeroberfläche auch Ganzzahlen außerhalb dieses Bereichs zugewiesen werden.

• Die Funktion throw http exception() lässt für den korrespondierenden Parameter (A) Zeichenfolgen für positive Ganzzahlen im Bereich 0 bis 999 zu.

  • Führende Nullen können für Werte <100 eingegeben und gespeichert werden. Für die Übernahme in die statusCode-Liste werden sie allerdings ignoriert.

 WARNUNG  Falls der Status Code 200 in der statusCodes-Liste enthalten ist, übersteuert die zugehörige Definition die Darstellung für den Rückgabewert in OpenAPI, die sich normalerweise auf den Typhinweise für die Variable response im Aktionsblock bezieht.

Beispiel:

 ANMERKUNG  Die Status Codes sind hier bewusst außerhalb des offiziellen Wertebereichs für HTTP Response Status Codes gewählt.

Endpunkt-Konfiguration:

Auszug aus der OpenAPI-Dokumentation für den Endpunkt:

Deklarierte Variablen (Baumansicht)

Die Baumansicht links neben dem Aktionsblock spiegelt im oberen Bereich ausgewählte Merkmale der Datenstruktur für die Endpunkt-Definition wieder.

Als letztes Element der obersten Hierarchieebene im “Baum” erscheint zusätzlich der Knoten “Deklarierte Variablen”, der informativ alle für den Aktionsblock deklarierten Variablen (inkl. Typhinweis) benennt.

Die Variablen in der folgenden Tabelle sind systemseitig deklariert. Sie können im Aktionsblock über den Variable-Wertauflöser deklariert werden.

 HINWEIS  Wenn der Knoten weitere “Deklarierte Variable” als Einträge enthält, gehen diese entweder auf Konfigurationen im Aktionsblock zurück oder aus der Definition der “URI” (s. oben: URI-Parameter) für den Endpunkt.

 ANMERKUNG  Die Aktualisierung der Baumansicht erfolgt während der Konfiguration ggf. erst “bei Berührung” des Baums (nach Änderungen im Aktionsblock). Geänderte “URI-Parameter” erscheinen dagegen sofort nach dem Verlassend des Felds in der Baumansicht.

Rückgabewert und Antworttyp

Der reguläre Rückgabewert für eine Endpunkt wird Aktionsblock durch eine Zuweisung an die response-Variable inhaltlich definiert.

Die formale Abbildung (Serialisierung) dieses Datenobjekt — also den gewünschten “Antworttyp” — bestimmt im allgemeinen Fall der für die Anfrage definierte Accept-Header.

 AUSNAHME  Wird der response-Variable ein Objekt des Typ “Inhalt” (Content) zugewiesen, findet keine automatische Serialisierung für den Rückgabewert statt. Stattdessen wird als Rückgabewert die “Nutzlast” des “Inhalt”-Objekts zur Verfügung gestellt. So kann z. B. eine Dateireferenz mit einer beliebig großen Datenmenge zurückgegeben werden. Der Content-Type für den Response Header wird dabei aus dem mediaType-Feld des “Inhalt”-Objekts übernommen.

 HINWEIS  Diese besondere Behandlung für den Typ “Inhalt” (Content) als Rückgabewert kann außer Kraft gesetzt werden, indem der systemseitig bereitgestellten Boolean-Variable mit dem Namen disableContentHandling im Aktionsblock der Wert true zugewiesen wird (s. Tabelle oben).

Anonymer vs. autorisierter Zugriff

Für jeden Endpunkt kann über die Option “Anonymer Zugriff” (allowAnonymousAccess) individuell entschieden werden, ob dieser für den Zugriff ohne Autorisierung — also für “anonymen Zugriff” — verfügbar sein soll.

• Bevor ein Endpunkt für den “anonymen Zugriff” freigegeben wird, sollten Sicherheitsaspekte bzgl. der über den Aktionsblock bereitgestellten Funktionalität sorgfältig geprüft werden.

• Der fehlende “Sitzungskontext” (Rolle der Session, Firma der Session, Benutzer der Session) kann bei Bedarf durch den Einsatz der Ausführen als-Ereignisaktion kompensiert werden.

  • Zum Ausführen einer Suche (Ereignisaktion) muss z. B. eine Rolle der Session vorliegen, die über Leserechte für gesuchte Entitätstypen verfügt.

  •  ACHTUNG  Falls eine Suche (Ereignisaktion) im Kontext Suche (Ereignisaktion)-Ereignisaktion konfiguriert ist, die eine Rolle der Session beansprucht, für die keine Besitzereinschränkungen gelten (typischerweise “Super User”), könnte der anonyme Endpunkt den Lesezugriff auf sensible Daten ohne Zugriffskontrolle ermöglichen.

 WICHTIG  Wenn der Zugriff auf einen Endpunkt über denselben Browser stattfindet, in dem bereits eine Lobster Data Platform-Sitzung angemeldet ist, greift automatisch das Session Cookie für diese Anmeldung, also der der bestehende “Sitzungskontext” (Rolle der Session, Firma der Session, Benutzer der Session). In diesem Fall kann bzw. muss ein “privates Browser-Fenster” (oder ein vom “angemeldeten” Browser losgelöster REST-Client) verwendet werden, um — z. B. für einfache Tests — ohne vorherige Abmeldung der Lobster Data Platform-Sitzung wirklich anonyme Aufrufe eines Endpunkts ausführen zu können.

Ansonsten sollte die Authentifizierung über OAuth2 für API Zugriffe erfolgen.

Tab-Reiter “Meta-Informationen”

Im Tab-Reiter Meta-Informationen können informative Angaben zur REST-API hinterlegt werden, die abhängig vom Aufrufkontext in der OpenAPI-Dokumentation erscheinen.