Call Switchboard via API

The following sections show how to call a switchboard via the HTTP API.

The user needs an API key for an API call. An API key can be created by an administrator in the user management. To do this, the administrator clicks on "Edit user" and then on the "API key" tab. An API key can be used in any number of API calls for any number of switchboards up to its revision.

Each switchboard has a call URL. This can be viewed in the PlexMap backend for the respective switchboard under "Edit switchboard" in the "Execution" tab. In the following, the placeholder APIURL is used for the URL and the placeholder KEY for the API key.

Es existieren nun folgende Aufrufmöglichkeiten:

1. With the program curl and the API key as GET parameter:

   curl APIURL?api_key=KEY

    

2. With the program curl and the API key as Header parameter:

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

    

3. With the program wget and the API key as GET parameter:

   wget -qO- APIURL?api_key=KEY

    

4. With the program wget and the API key as Header parameter:

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

If data is to be passed to the switchboard during the HTTP call (e.g. parameters, polygons or files), the switchboard needs one or more inputs. If the HTTP call is to return results from the switchboard, the switchboard needs one or more outputs. If nothing like this should happen, this section can be skipped.

For instructions on how to define an input or output, see the section Defining Inputs and Outputs.

The defined inputs can then be appended as GET parameters to the API call. For example, an input of type String with the name id can be appended via &id=abc1234. An input of type Bbox can be passed via &bounds=10,10,20,20.
 

The parameters can also be passed as a POST call. In this case, the POST body must contain a JSON object. The keys of this object are the names of the defined inputs and the values are the data for the respective input. Unlike the GET, these must already be lists, since in the switchboard each record is a list.
 

The examples analogous to the GET case then look like this:

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

If the GET parameter &async=true is also specified, the system does not wait for the switchboard to execute successfully, but returns a response directly. This response contains a result_url. If this URL is queried, the progress is returned and if the execution was successful, the result is returned.

Different output types can be selected in the API call. For this, append &output_format=[json|text|file] to the URL.

JSON is the default output format. Here the status and all switchboard outputs are returned in a JSON structure:

{"status": "ok", "outputs": {"value1": [1, 2, 3]}}

With the output format "Text" the output is serialized as plain text:

The output format file is used to return a file from the API call. There is a requirement for this that the switchboard also has an output of type File. The following are some examples of how the procedure can then be used to save a file with the curl or wget program.

1. With the program curl and the API key as GET parameter:

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

    

2. With the program curl and the API key as Header parameter:

   curl -H "X-Api-Key: KEY" APIURL&output_format=file --output result.zip

    

3. With the program wget and the API key as GET parameter:

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

    

4. With the program wget and the API key as Header parameter:

   wget -q -O result.zip '--header=X-Api-Key: KEY' APIURL&output_format=file