Switchboard via API aufrufen¶

In dieser Anleitung wird gezeigt, wie ein Switchboard via der HTTP-API aufgerufen werden kann.

API-Schlüssel als Voraussetzung¶

Der Benutzer benötigt für einen API-Aufruf einen API-Schlüssel. Ein API-Schlüssel kann von einem Administrator in der Benutzerverwaltung erzeugt werden. Hierzu klickt der Administrator auf „Benutzer bearbeiten“ und dann auf den Reiter „API-Schlüssel“. Ein API-Schlüssel kann bis zur dessen Revision in beliebig vielen API-Aufrufen für beliebig viele Switchboards verwendet werden.

API-Aufruf¶

Jedes Switchboard hat eine Aufruf-URL. Diese ist im PlexMap Backend für das jeweilige Switchboard unter „Switchboard bearbeiten“ im Reiter „Ausführung“ einsehbar. Im folgenden wird für die URL der Platzhalter APIURL und für den API-Schlüssel der Plathalter KEY verwendet.

Es existieren nun folgende Aufrufmöglichkeiten:

Mit dem Programm curl und dem API-Schlüssel als GET Parameter:
curl APIURL?api_key=KEY
Mit dem Programm curl und dem API-Schlüssel als Header Parameter:
curl -H "X-Api-Key: KEY" APIURL
Mit dem Programm wget und dem API-Schlüssel als GET Parameter:
wget -qO- APIURL?api_key=KEY
Mit dem Programm wget und dem API-Schlüssel als Header Parameter:
wget -qO- '--header=X-Api-Key: KEY' APIURL

Parametrisierter Aufruf¶

Wenn während des HTTP-Aufrufes Daten an das Switchboard übergeben werden sollen (z.B. Parameter, Polygone oder Dateien), benötigt das Switchboard einen oder mehrere Eingänge. Soll der HTTP-Aufruf Ergebnisse aus dem Switchboard zurückgeben, benötigt das Switchboard einen oder mehre Ausgänge. Wenn nichts dergleichen passieren soll, kann diese Abschnitt übersprungen werden.

Eine Anleitung, wie sie eine Ein- bzw Ausgabe definieren können, finden Sie im Abschnitt Ein- und Ausgaben definieren.

Übergabe der Parameter¶

Die definierten Eingänge können dann als GET Parameter an den API-Aufruf angehängt werden. Beispielsweise kann ein Eingang vom Typ String mit dem Namen id via &id=abc1234 angehängt werden. Ein Eingang vom Typ BBOX mit dem Namen bounds kann via &bounds=10,10,20,20 übergeben werden.

Die Parameter können auch als POST-Aufruf übergeben werden. In diesem Fall muss der POST-Body ein JSON-Objekt enthalten. Die Schlüssel dieses Objektes sind die Namen der definierten Eingänge und die Werte sind die Daten für den jeweiligen Eingang. Anders als beim GET müssen diese schon als Listen vorliegen, da im Switchboard jeder Datensatz eine Liste ist.

Die Beispiele analog zum GET-Fall sehen dann wie folgt aus: {"id":["abc1234"]} und {"bounds":[[10,10,20,20]]}.

Asynchroner Aufruf¶

Wird zusätzlich der GET Parameter &async=true angegeben, wird nicht auf das erfolgreiche Ausführen des Switchboards gewartet, sondern direkt eine Antwort zurückgeben. Diese Antwort enthält eine result_url. Wird diese URL abgefragt, wird der Fortschritt und bei erfolgreicher Ausführung das Ergebnis zurückgegeben.

Ausgabeformate¶

Beim API-Aufruf können verschiedene Ausgabetypen gewählt werden. Hängen Sie hierfür &output_format=[json|text|file] an die URL.

JSON¶

JSON ist das Standardausgabeformat. Hierbei wird der Status und alle Switchboard-Ausgaben in einer JSON-Struktur zurückgegeben:

{"status": "ok", "outputs": {"wert1": [1, 2, 3]}}

Text¶

Mit dem Ausgabeformat „Text“ wird die Ausgabe als einfacher Text serialisiert:

1
2
3

File¶

Mit dem Ausgabeformat file wird eine Datei vom API-Aufruf zurückgegeben. Hierfür gibt es die Vorraussetzung, dass das Switchboard auch eine Ausgabe vom Typ File hat. Es folgen einige Bespiele, wie das Vorgehen dann verwendet werden kann, um eine Datei mit dem Programm curl oder wget zu speichern.

Mit dem Programm curl und dem API-Schlüssel als GET Parameter:
curl APIURL?api_key=KEY&output_format=file --output ergebnis.zip
Mit dem Programm curl und dem API-Schlüssel als Header Parameter:
curl -H "X-Api-Key: KEY" APIURL&output_format=file --output ergebnis.zip
Mit dem Programm wget und dem API-Schlüssel als GET Parameter:
wget -q -O ergebnis.zip APIURL?api_key=KEY&output_format=file
Mit dem Programm wget und dem API-Schlüssel als Header Parameter:
wget -q -O ergebnis.zip '--header=X-Api-Key: KEY' APIURL&output_format=file