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 :ref:`workflow-input-output`.

Ü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 :ref:`type-string`
mit dem Namen ``id`` via ``&id=abc1234`` angehängt werden. Ein Eingang vom Typ
:ref:`type-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 :ref:`type-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