Campingleitsystem API

Das Campingleitsystem ist ein Portal für bayerische Campingplätze. Die Verfügbarkeit der Campingplätze wird durch ein Ampelsystem visualisiert mit den drei Zuständen voll (also nicht verfügbar), fast voll und frei (also verfügbar). Campingplätze können diese Verfügbarkeiten jeweils bis zum Januar des übernächsten Jahres in der Eintragsverwaltung anpassen.

Campingplätze, die bereits an Buchungssysteme oder Channel Manager angeschlossen sind oder interne Systeme für Reservierungen und Buchungen verwenden, können ihre Daten auch über eine einfache API automatisiert anpassen. Über die API kann für jeden (verwalteten) Campingplatz pro Tag die Anzahl freie Plätze angegeben werden. Dieser Zustand kann bei Änderungen jederzeit über unsere API aktualisiert werden.

Zugriffsdaten für die API

Über den Campingplatz-Login auf dem Campingleitsystem können sich Verwalter selbst den Zugang für die API aktivieren. Dabei wird ein Token erstellt (JWT). Mit diesem Token kann die Verfügbarkeit für alle zugeordneten Campingplätze des Verwalters per API angepasst werden.

Die Seite zum Aktivieren der API kann über den Link Verfügbarkeit via API aktualisieren auf der Seite Verfügbarkeit im Eintragsmanagement aufgerufen werden. Auf der Seite werden die momentan verwalteten Campingplätze angezeigt mit den Informationen, ob der API-Zugang für diese aktiviert ist:

Bei den meisten Verwaltern wird hier nur ein einziger Campingplatz angezeigt, es gibt jedoch auch Zugänge, die mehrere Campingplätze verwalten. Über den Button Token anlegen kann dann ein Token angelegt werden, mit dem die Verfügbarkeiten für alle verwalteten Einträge automatisiert über die JSON-API angepasst werden können.

Wenn ein Token existiert, wird dieses angezeigt mit den enthaltenen Informationen, wie z. B. Ausstellungsdatum und IDs der enthaltenen Campingplätze:

Für den Zugriff auf die API wird nur das Token (JWT) selbst benötigt, das über den Button Token kopieren in die Zwischenablage kopiert werden kann. Außerdem werden die IDs der Campingplätze benötigt, für die jeweils Verfügbarkeiten angepasst werden sollen.

Token bei zusätzlichen Campingplätzen

Falls bei diesem Login später noch ein weiterer Campingplatz hinzukommt, muss wieder ein neues Token erstellt werden, was auch diesen neuen Platz mit einschließt. Beim Neu-Erstellen von Token wird das bisherige Token ungültig und kann nicht mehr verwendet werden.

Token erneuern bei missbräuchlicher Verwendung

Bei missbräuchlicher Verwendung eines Tokens kann dieses unmittelbar deaktiviert werden, indem hier ein neues Token angelegt wird. Das alte Token ist dann sofort gesperrt und kann nicht mehr verwendet werden.

Verfügbarkeiten über API aktualisieren

Für das Ändern von Verfügbarkeiten gibt es einen API-Endpunkt (genaue URL auch in der Eintragsverwaltung mit Token). Im Authorization-Header muss das Token (siehe oben) mitgesendet werden. Als Präfix kann hier z. B. „Bearer“ oder „Token“ stehen.

Der Request erfolgt per POST. Der Body ist ein JSON-Objekt, das für ein bis mehrere Campingplätze Verfügbarkeiten enthält.

Datenstruktur

Das Root-Element enthält ein Array mit Verfügbarkeiten für einen spezifischen Campingplatz. Jede dieser Verfügbarkeiten hat eine EntryId mit der eindeutigen Id des Campingplatzes, für den die Verfügbarkeiten angepasst werden sollen. Außerdem die Werte für die Verfügbarkeiten selbst. Diese Verfügbarkeiten bestehen aus einem Datums-Feld im Format Jahr-Monat-Tag (zehnstellig: „2022-09-22“) und der Anzahl an freien Stellplätzen für diesen Tag.

{
    "Availabilities" : [
        {
            "EntryId" : 188,
            "DailyAvailabilities" : [
                {
                    "Date": "2022-09-21",
                    "AvailableCount": 5
                }, {
                    "Date": "2022-09-22",
                    "AvailableCount": 8
                }                
            ]
        }
    ]
}

Beispiel-Request per Postman

Postman ist ein weit verbreitetes Tool, um APIs zu testen und auch zu bauen. Hier eine exemplarische Beschreibung, wie ein Request per Postman durchgeführt werden kann. Das erleichtert dann auch die Umsetzung in der jeweiligen Technologie bzw. Programmiersprache.

Zuerst müssen die Grundeinstellungen bzw. die Autorisierung eingestellt werden:

1. Http-Methode ist POST
2. Die Url zum Api-Endpunkt zum Ändern von Verfügbarkeitsdaten
3. Sicherheitseinstellungen werden auf dem Tab Authorization eingestellt
4. Hier kann als Typ BearerToken ausgewählt werden
5. Als Token muss dann das Token eingefügt werden, das man sich in der Eintragsverwaltung selbst erzeugen kann (siehe oben).

Danach kann im Body das JSON mit den Verfügbarkeiten übertragen werden:

1. In den Reiter Body wechseln
2. als Typ raw auswählen
3. Dann JSON als Inhaltstyp
4. JSON-Objekt in den Body einfügen: die Eintrags-Id muss natürlich mit einem Eintrag des verwendeten Tokens übereinstimmen. Ansonsten kann das JSON aus dem Beispiel weiter oben auch als Template kopiert und angepasst werden.

Wenn alles korrekt funktioniert hat, wird als Rückgabeobjekt ein „isSuccess“: true zurückgesendet und eine leere Fehlerliste: