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:

  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
    

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=XMIN,YMIN,XMAX,YMAX übergeben werden.

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.

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

    curl 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