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=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 :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