Switchboard via API aufrufen

In den folgenden Abschnitten wird gezeigt, wie ein Switchboard via HTTP-API aufgerufen werden kann.

Benutzer:innen benötigen für einen API-Aufruf einen API-Schlüssel. Ein API-Schlüssel kann von Administrator:innen in der Benutzerverwaltung erzeugt werden. 

Hierzu klicken Administrator:innen auf „Benutzer bearbeiten“ und dann auf den Reiter „API-Schlüssel“. Ein API-Schlüssel kann bis zu dessen Revision in beliebig vielen API-Aufrufen für beliebig viele Switchboards verwendet werden.

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 Platzhalter KEY verwendet.

Es existieren nun folgende Aufrufmöglichkeiten:

1. Mit dem Programm curl und dem API-Schlüssel als GET Parameter:

   curl APIURL?api_key=KEY

    

2. Mit dem Programm curl und dem API-Schlüssel als Header Parameter:

   curl -H "X-Api-Key: KEY" APIURL

    

3. Mit dem Programm wget und dem API-Schlüssel als GET Parameter:

   wget -qO- APIURL?api_key=KEY

    

4. Mit dem Programm wget und dem API-Schlüssel als Header Parameter:

   wget -qO- '--header=X-Api-Key: KEY' APIURL

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 unter Ein- und Ausgaben definieren.

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 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]]}.

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.

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

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]}}

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

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.

1. Mit dem Programm curl und dem API-Schlüssel als GET Parameter:

   url APIURL?api_key=KEY&output_format=file --output ergebnis.zip

    

2. 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

    

3. Mit dem Programm wget und dem API-Schlüssel als GET Parameter:

   wget -q -O ergebnis.zip APIURL?api_key=KEY&output_format=file

    

4. 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