Die Domtechnik

REST-API

Voraussetzungen

Daten

Sie können über diese Schnittstelle folgende Daten zum Modellbau des Kölner Domes auslesen:

Statuscodes

Zusätzlich zu den bereits bestehenden Standard HTTP-Statuscodes, sind hier die folgenden erweiterten applikationsspezifischen Statusmeldungen angeführt. Die Schnittstelle kann folgende Statusmeldungen zurückgeben:

Beispiel

In diesem Beispiel lesen wir den Status und das aktuell laufende Musikstück der Orgel aus. Um das folgende Beispiel besser zu verstehen, gehen wir Schritt für Schritt näher auf jeden Parameter des Befehls cURL ein.

• Aufrufen von cURL curl
  Im ersten Schritt wird der Befehl cURL aufgerufen. Beachten Sie, dass cURL standardmäßig unter Windows, macOS oder Linux-Distributionen nicht verfügbar ist. Es bedarf hierbei einer manuellen Installation des Programms.


• HTTP-Methode --get
  Wir geben nun durch den Parameter "--get" die zu verwendende HTTP-Methode an. Welche Methode Sie verwenden müssen, sehen Sie in der Tabelle unter dem Abschnitt "Daten".


• Autorisierung durch HTTP-Header --header "x-kdrtwp-get-secret: <METHOD_SECRET>"
  Die Autorisierung gegen die API erfolgt durch die Bekanntgabe des Method-Secrets im HTTP-Header. Da wir in diesem Beispiel die Methode "GET" verwenden, erweitern wir den Header um das Feld "x-kdrtwp-get-secret" und geben darin den jeweiligen Method-Secret an. Der Method-Secret ist ein statischer Schlüssel und muss pro HTTP-Methode angegeben werden.


• Befehl --data-urlencode "command=audio 2"
  Über die API können unterschiedlichste Daten zum Miniatur-Dom ausgelesen werden. In diesem Beispiel lesen wir den Status der Orgel und das aktuell laufende Musikstück aus. Wir geben daher mit dem cURL-Parameter "--data-urlencode" den Befehl "audio 2" an. Eine Übersicht über weitere Befehle finden Sie in der Tabelle unter dem Abschnitt "Daten".


• Authentifizierung und Bekanntgabe der API-URL https://api.derkoelnerdom.at/<API_KEY>
  Abschließend geben wir noch die URL der API und zur Authentifizierung gegen die Schnittstelle den entsprechenden API-Schlüssel bekannt.

Sie sehen unten angeführt den Befehl zum Auslesen des Zustandes der Orgel und das aktuell laufende Musikstück:

curl \
    --get \
    --header "x-kdrtwp-get-secret: <METHOD_SECRET>" \
    --data-urlencode "command=audio 2" \
    https://api.derkoelnerdom.at/<API_KEY>

                

Das Ergebnis der Anfrage wird in Form eines JSON-Objekts als Antwort zurückgegeben:

{
    "meta": {
        "health": {
            "kdsm": 1
        },
        "time": {
            "zone": "Europe/Vienna",
            "syn": "06 Jan 2021 14:55:30",
            "ack": "06 Jan 2021 14:55:30"
        },
        "status": {
            "name": "OK",
            "code": "100"
        },
        "request": {
            "syn": {
                "command": "audio 2"
            },
            "ack": {
                "data": [
                    "play",
                    "FFFF FFFF FFFF FFFF",
                    "Klaus Wallrath - Es führt drei König Gottes Hand"
                ]
            }
        }
    }
}
                

In der folgenden Tabelle werden die Details der Objektstruktur (Antwort) näher erläutert: