Anmeldung

Spielberichte übermitteln

Spielberichte können als HTML direkt an die Schnittstelle geschickt werden und erscheinen sofort auf der Neuigkeitenseite:

Der Token wird auf dem Server über die Umgebungsvariable BGRW_REPORT_TOKEN festgelegt. Titel wird aus dem HTML übernommen (<title> oder erste Überschrift) oder per ?title=... gesetzt. Die optionale ?externeId=... ist der Schlüssel des anliefernden Systems: ein Bericht mit bekannter id wird aktualisiert statt neu angelegt, und dieselbe id verknüpft den Bericht mit dem zugehörigen Termin („Spielbericht lesen“ in der Terminliste).

Eingegangene Spielberichte erscheinen im Bereich „Neuigkeiten“ unter den vorhandenen Beiträgen und lassen sich dort bearbeiten oder löschen.

Termine übermitteln

Termine nimmt die Schnittstelle als JSON entgegen (gleicher Token wie bei den Spielberichten). Ein Termin mit bekannter externeId wird aktualisiert statt neu angelegt – der Import kann also einfach wiederholt werden:

Pflichtfelder: typ (LIGASPIEL oder AUSRICHTUNG), disziplin (POOL oder CARAMBOL) und datum (ISO-8601, UTC). Ligaspiele brauchen liga, eigeneMannschaft, gegner und heimspiel; Ausrichtungen stattdessen name, dazu optional runde (VORRUNDE/ZWISCHENRUNDE/ENDRUNDE) und teilnehmer (Liste von Spielernamen).

Die externeId verknüpft den Termin mit dem Spielbericht: wird der Bericht später mit derselben id hochgeladen, zeigt die Terminliste „Spielbericht lesen“. Übermittelte Termine erscheinen im Bereich „Termine“ als „extern gepflegt“ und lassen sich dort auch bearbeiten – bis der nächste Import die Änderung überschreibt.

Termin löschen

Ein einzelner Termin wird über seine id entfernt (Feld id aus der Antwort beim Anlegen), bei Erfolg ist der HTTP Status 204:

Das Sammellöschen (DELETE /api/termine ohne id) steht der Schnittstelle bewusst nicht offen – es ist Administratoren im Login-Bereich vorbehalten.

Vereine übermitteln

Vereine für die Karte nimmt die Schnittstelle als JSON entgegen (gleicher Token wie bei Spielberichten und Terminen). Ein Verein mit bekannter externeId – ohne externeId: mit bekannter Homepage – wird aktualisiert statt neu angelegt (HTTP 200 statt 201); ohne beides wird immer neu angelegt:

Pflichtfelder: name, ort und bundesland (eines der 16 Bundesländer, ausgeschrieben). Optional url (Homepage, http/https) und telefon (Ziffern, Leerzeichen, + - / ( )). disziplinen ist eine Liste aus Pool, Carambol, Snooker und Kegelbillard (Karambol/Kegel werden umgesetzt). Optional das Spiellokal: spiellokal (Name), strasse (mit Hausnummer) und plz – aus der Adresse bestimmt der Server die Position auf der Karte (über OpenStreetMap); ohne Adresse oder wenn sie nicht gefunden wird, die Ortsmitte. Genaue Koordinaten lassen sich stattdessen als lat und lon (nur gemeinsam) mitschicken – sie haben Vorrang.

Mehrere Vereine auf einmal: dasselbe als JSON-Array an POST /api/billardvereine/import – alles oder nichts, die Fehlermeldung nennt den fehlerhaften Eintrag. Ohne Koordinaten dauert jeder Eintrag gut eine Sekunde (Takt des Ortsdienstes).

Verein ändern oder löschen

Über die id (Feld id aus der Antwort): PUT /api/billardvereine/<id> mit denselben Feldern ändert den Verein (die externeId bleibt dabei unverändert), DELETE entfernt ihn (HTTP 204):