Documentation Index

Fetch the complete documentation index at: https://docs.lobster-world.com/llms.txt

Use this file to discover all available pages before exploring further.

REST API: URI und URI-Parameter

Prev Next

Dieses Topic beschreibt die Konfiguration der Eigenschaft URI (uri) eines REST-API-Endpunkts und die Verwendung von URI-Parametern. Eine Übersicht über die REST API-Konfiguration finden Sie unter REST API.

URI: Basisform

Im einfachsten Fall identifiziert die URI-Eigenschaft den Endpunkt über eine statische Zeichenfolge. Optional kann diese Zeichenfolge ein durch Schrägstriche (/) gegliederter Pfad sein.

Sie können auch variable Bestandteile als URI-Parameter deklarieren. URI-Parameter bilden Abschnitte der zur Laufzeit adressierten URI auf Variablen ab, die Sie im Aktionsblock nutzen.

Beispiel: Ein Endpunkt ./demo/deleteItem/{id} mit der DELETE-Methode löscht eine Entität. Der URI-Parameter {id} identifiziert die zu löschende Entität über deren interne ID (id).

 HINWEIS Ein URI-Parameter liefert immer einen Textwert (String). Im Aktionsblock können explizite Typumwandlungen nötig sein.

Der Aktionsblock für den Endpunkt deleteItem erwartet zur Laufzeit eine Ziffernfolge. Diese muss dem Long-Wert der Eigenschaft ID (id) der zu löschenden Entität entsprechen.

Die Ausführen mit-Ereignisaktion definiert die zu löschende Entität über den Objekt-Wertauflöser als temporäres Bezugsobjekt für die Später löschen-Ereignisaktion im inneren Aktionsblock.

Über den String-Wert aus dem URI-Parameter {id} greift eine zweistufige Wertauflöserkette (Verketteter Wertauflöser) auf die zu löschende Entität zu:

  • Der Variable-Wertauflöser wandelt den String in einen Long um. Dazu setzen Sie den Parameter Typ beim Lesezugriff entsprechend.

  • Der verkettete Eingabeobjekt (Typsicher)-Wertauflöser mit dem Typ „Ereignis" (Incident) liefert die Incident-Entität, deren ID (id) mit dem bereitgestellten Long-Wert übereinstimmt. Existiert keine passende Entität, liefert der Wertauflöser $null. Ohne weitere Vorkehrungen erhält der Aufrufer keine Fehlermeldung.

URI-Parameter: Details

Der Textwert der Eigenschaft URI (uri) kann neben Klartextzeichen auch URI-Parameter im Format {<variable>} enthalten. Zur Laufzeit bildet die Plattform die korrespondierenden Teilzeichenfolgen aus der Aufrufadresse als Textwerte auf Variablen ab (siehe Variable). Auf diese Variablen greifen Sie im Aktionsblock zu.

 WICHTIG  Maskieren Sie HTTP-relevante Sonderzeichen in der zur Laufzeit übergebenen Zeichenfolge über URL Enkodierung. Beispiele: %20 für das Leerzeichen, %2F für einen Schrägstrich (/), %3F für das Fragezeichen (?).

Die Zeichenfolge für URI kann mehrere URI-Parameter enthalten. Zwischen zwei URI-Parametern setzen Sie ein geeignetes Trennzeichen. Das Trennzeichen darf nicht unmaskiert in den zur Laufzeit bereitgestellten Strings vorkommen.

 WICHTIG  Sämtliche URI-Parameter behandelt die Plattform als Pflichtangaben. Eine leere Zeichenfolge ("") lässt sich nicht als %00 übergeben. Das schränkt den Einsatz von Standardwert ein.

 HINWEIS Verwenden Sie ein HTTP-relevantes Sonderzeichen als Trennzeichen, müssen Sie dieses ebenfalls maskieren. Beispiel: %23 statt #.

Beispiel: URI-Parameter mit Trennzeichen

  • Basis-URI der API-Definition (baseUri): demo.

  • Der Endpunkt liefert per GET einen Ausgabetext. Der Text enthält die Systemzeit mit per URI wählbarer Zeitzone und Formatierung.

  • Zeichenfolge der URI (uri): getTime/{zone}|{format}

  • Beispielaufruf: https://<platform-host>/api/demo/getTime/Europe%2FAthens|EEEE%20HH:mm%20z

  • Der Text zwischen getTime/ und dem Pipe-Symbol (|) erscheint dekodiert als Europe/Athens in der Variable zone.

  • Der Text nach dem Pipe-Symbol (|) erscheint als EEEE HH:mm z in der Variable format.

  • Aus diesen Textparametern erzeugt der Aktionsblock den gewünschten Ausgabetext, zum Beispiel Mittwoch 19:40 Europe/Athens.

 HINWEIS Das Datumsformat enthält lokalisierungspflichtige Bestandteile, hier den Volltext für den Wochentag (Pattern EEEE). Um die Ausgabesprache optional wählbar zu machen, ergänzen Sie einen Query-Parameter locale. Der Aufruf lautet dann zum Beispiel: https://<platform-host>/api/demo/getTime/Europe%2FAthens|EEEE%20HH:mm%20z?locale=fr

Auf den Parameter locale greifen Sie im Aktionsblock über die systemseitig befüllte Variable queryParameters per Map-Wert-Wertauflöser mit dem Schlüssel locale zu.

Der Ausgabetext für die Sprache „Französisch" (fr) lautet dann zum Beispiel: mercredi 19:40 Europe/Athens.

Dynamische Pfade über reguläre Ausdrücke

Am Ende der URI-Zeichenfolge geben Sie einen dynamischen Pfad über einen URI-Parameter mit folgendem Schema an: {<variable>: <regExp>}

  • Stimmt der korrespondierende Abschnitt der zur Laufzeit adressierten URI vollständig mit dem regulären Ausdruck (<regExp>) überein, übernimmt die Plattform ihn in die Variable (<variable>).

  • Stimmt der Abschnitt nicht mit dem regulären Ausdruck überein, schlägt der Aufruf mit Fehler 404 - NOT FOUND fehl.

Beispiel: dynamischer Pfad

  • Basis-URI der API-Definition (baseUri): demo.

  • Der Endpunkt liefert per GET Daten zu einem Künstler in einer Mediendatenbank.

  • Zeichenfolge der URI (uri): getArtist/{name: .+}

  • Der reguläre Ausdruck .+ akzeptiert beliebige Zeichen, solange mindestens ein Zeichen vorliegt. Beispiele: U2, UB40, AC/DC, Van%20Halen, Primus, MEGADETH.

  • Mit dem regulären Ausdruck [A-Z]+[0-9]* wären aus dieser Liste nur U2, UB40 und MEGADETH adressierbar.

  • Mit dem regulären Ausdruck ([a-zA-Z/]|%20|%2F)+[0-9]* sind wieder alle Beispiele kompatibel. Für AC/DC funktioniert dann auch die bevorzugte URL-encodierte Schreibweise (AC%2FDC).

Verwandte Artikel