Request Chaining

Für kürzere Round-Trip-Times (rtt) und eine bessere Auswahl der API Ergebnisse können Requests zusammengesetzt werden (chaining).

info

Request-Chaining sollte nur zusammen mit dem Konfigurationsparameter strict verwendet werden, da es sonst zu undefiniertem Verhalten kommen kann.

Die Funktionen

Um mehrere Funktionen gleichzeitig aufzurufen, muss im Key functions statt eines einzelnen Methodennamens (z.B. Login) eine Liste dieser mitgegeben werden (z.B. GetBuildingInfo,LoadTag)

Die Parameter

Passend muss in korrekter Reihenfolge die Definiton der Parameter mitgegeben werden, wobei die erste übergebene Funktion den Index 0 hat. Optional kann auch statt einem fixen Index der Wert * übergeben werden, wobei die Funktion dann auf alle Ergebnisse von diesem Typen angewendet wird.

Beispiel:

↪ Request

{
    "0": {
        "building_id": 19
    },
    "1": {
        "tag": "$GetBuildingInfo.0.roottag"
    }
}

↩ Response

{
    "GetBuildingInfo": [
        {
            < ... >
        }
    ],
    "LoadTag": [
        {
            < ... >
        }
    ]
}

Verküpfung von Antworten

In vielen Situationen hängt der oder die Eingabeparameter einer API Methode von den vorhergehenden Methoden ab.

Um diese Requests nicht aufsplitten zu müssen, können Ergebnisse referenziert werden.

Hierfür wird statt eines konkreten Parameters eine Referenz nach folgendem Format übermittelt:

$<MethodenName>.<Idx>.<ParameterName>.

info

Falls ein Parameter einen Array oder Objekttypen enthält, kann der auszuwählende Wert explitit (siehe Beispiel), oder mit Wildcard (*) definiert werden:

$<MethodenName>.<Idx>.<ParameterName>.0.<SubparameterName>.

Wird ein Wildcard verwendet, so wird die Methode so oft aufgerufen wie es entsprechende Einträge im Array gibt.

Die Referenz als solche beginnt immer mit einem $ Zeichen, gefolgt von dem Methodennamen der Antwortmethode aus welcher der Parameter extrahiert werden soll. Handelt es sich beim Ergebnis um ein Array (wie oben), definiert die Zahl nach dem Punkt, welches der Ergebnisse verwendet werden soll. Im Empfholenen Modus strict werden die Ergebnisse immer in ein Array verpackt, somit muss die entsprechende Antwort mit [0-9]+ oder * ausgewählt werden.

info

Wildcards können auch verwendet werden, wenn es nur ein Ergebnis gibt.

Wichtig: Es muss sichergestellt sein, dass es ausreichend Ergebnisse gibt.

Danach wird der Name des Parameters aus dem Ergebnis referenziert.

info

There can not be more then one parameter wildcard per request, configurations like $GetBuildingInfo.0.allTags.*.importantTags.*.tag_id will be invalid and lead to empty results.

Tipp: Am einfachsten ist es bei der Entwicklung, die Aufrufe in Postman einzeln zu simulieren und dann zusammenzusetzen.