Switchboard via API aufrufen

In den folgenden Abschnitten wird gezeigt, wie ein Switchboard über die HTTP-API gestartet wird und wie Sie Status und Ergebnisse abfragen können.

Für API-Aufrufe wird ein persönlicher API-Schlüssel benötigt. Administrator:innen können diesen in der Benutzerverwaltung anlegen. Hierzu klicken Sie auf "Benutzer bearbeiten", nehmen den Reiter "API-Schlüssel" und wählen anschließend "NEUEN API-SCHLÜSSEL ERZEUGEN". 

Der so erzeugte Schlüssel kann, bis zu dessen Revision, für beliebig viele API-Aufrufe und beliebig viele Switchboards verwendet werden.

Zu jedem Switchboard werden im PlexMap Backend unter "Switchboard bearbeiten" im Reiter "Ausführung" mehrere API-Endpunkte angezeigt:

• Run endpoint: startet die Ausführung des Switchboards

• Status endpoint: liefert den aktuellen Ausführungsstatus

• Result endpoint: stellt die Ergebnisse einer Ausführung bereit

Im Folgenden werden diese Platzhalter verwendet:

• RUN_URL für den Run-Endpunkt
• STATUS_URL für den Status-Endpunkt
• RESULT_URL für den Ergebnis-Endpunkt
• KEY für den API-Schlüssel

Es gibt mehrere Wege, die API aufzurufen:

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

   curl "RUN_URL?api_key=KEY"

    

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

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

    

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

   wget -qO- "RUN_URL?api_key=KEY"

    

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

   wget -qO- --header="X-Api-Key: KEY" "RUN_URL"
    

Nach dem erfolgreichen Aufruf der RUN_URL wird das Switchboard automatisch initialisiert. Im Anschluss können die Endpunkte STATUS_URL (zur Überwachung des Fortschritts) sowie RESULT_URL (zum Abrufen der Ergebnisse) angesprochen werden. 
Die Übergabe des API-Keys erfolgt hier simultan nach dem oben beschriebenen Schema.

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.

• Eingang vom Typ String id : &id=abc1234
• Eingang vom Typ Bbox : &bounds=10,10,20,20 
   

Die Parameter können auch als POST-Aufruf (JSON) ü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.

• {"id":["abc1234"]}
• {"bounds":[[10,10,20,20]]}
   

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:

{"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:

   curl "RESULT_URL?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" "RESULT_URL?output_format=file" --output ergebnis.zip

    

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

   wget -q -O ergebnis.zip "RESULT_URL?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" "RESULT_URL?output_format=file"