REST-API-Schnittstelle
Um eine Bereitstellung aktueller Spielbetriebsdaten für Presse und Vereine zu ermöglichen, wurde für SAMS eine REST-API-Schnittstelle entwickelt.
Zugriffsschlüssel
Um die Schnittstelle zu verwenden, ist ein individueller Zugriffsschlüssel (API-Key) nötig, der vom jeweiligen Verband vergeben wird. Fordern Sie den Key bitte von der zentralen Support-Adresse Ihres Verbandes ab.
Abfrage-Limit
Um den Service der REST-API-Schnittstelle zu gewährleisten unterliegt das Abfragen der Schnittstelle einem allgemeinen Rate-Limit. Dieses Limit gilt für alle Clients und alle Schnittstellen und liegt bei 5 Anfragen pro Sekunde. Das heißt, dass zwischen den Abfragen jeweils 200ms verstreichen müssen. Wird diese Spanne unterschritten, werden die Anfragen abgelehnt.
Die Anzahl der Zugriffe pro Tag und Schlüssel ist begrenzt, um den Server vor versehentlicher Überlastung zu schützen. Wird die Anzahl der Zugriffe pro Tag überschritten, ist der Schlüssel bis zum nächsten Tag gesperrt.
Abfragen
Sämtliche Abfragen sind über das Schema https://<verbandsadresse>/api/v2/<abfrage> erreichbar. Der API-Key muss als Header mit dem Namen "X-API-KEY" bei jeder Abfrage mitgegeben werden. Die Pfad-Übersicht unter "/api/v2/" und die Swagger-Dokumentation unter "/api/v2/swagger.json" sind ohne API-Key erreichbar.
Die Adressen lauten:
-- Bundesliga --
- für die Bundesligen: https://www.volleyball-bundesliga.de/
-- DVV Ligen --
- für die Dritten Ligen des DVV: https://www.dvv-ligen.de/
- für die Regionalliga West, Nordost, Ost und Südwest (verwaltet im DVV SAMS): https://www.dvv-ligen.de/
- für die Regionalliga Süd (verwaltet im DVV SAMS): https://www.dvv-ligen.de/
- für die Regionalliga Nord (verwaltet im DVV SAMS): https://www.dvv-ligen.de/
- für die Regionalliga Nordwest (verwaltet im DVV SAMS): https://www.dvv-ligen.de/
-- Landesverbände --
- für den SHVV (Schleswig-Holstein): https://www.shvv.de/
- für den VVRP (Rheinland-Pfalz): https://www.vvrp.de/
- für die Badischen Volleyballverbände: https://www.volleyball-baden.de/
- für den SSVB (Sachsen): https://www.ssvb.org/
- für den NWVV (Niedersachsen/Bremen): https://www.nwvv.de/
- für den TVV (Thüringen): https://www.tv-v.de/
- für den VLW (Württemberg): https://vlw-online.de/
- für den HVV (Hessen): https://hessen-volley.de/
- für den SVV (Saarland): https://www.volley-saar.de/
- für den VVB (Berlin): https://vvb.sams-server.de/
- für den VVSA (Sachsen-Anhalt): https://vvsa.sams-server.de/
- für den WVV (NRW): https://wvv.sams-server.de/
-- International --
- für den FLVB (Luxemburg): https://flvb.sams-server.de/
Beispielsweise also https://www.volleyball-bundesliga.de/api/v2/leagues/<leagueUuid>/rankings zum Abrufen der Tabellen der Spielrunde mit UUID <leagueUuid>.
Mithilfe des Query-Parameters "association" kann man mithilfe der UUID eines Verbands nur Entitäten abfragen, die entweder direkt zum angegebenen Verband gehören oder allen darunter liegenden Verbänden, die kein Landesverband oder die Volleyball Bundesliga sind. Beispiel: /api/v2/match-days?association=<associationUuid>
Vollständige Dokumentation
Unter der URL-Endung "/api/v2/swagger.json" erhält man eine json-Datei, die eine vollständige Dokumentation der REST API Endpunkte darstellt. Diese Datei kann in das Swagger Editor Tool (https://swagger.io/tools/swagger-editor/) geladen werden, um genaue Informationen zu allen REST API Endpunkten und ihren Parametern zu erhalten. Eine weitere Möglichkeit, die vollständige Dokumentation zu erhalten, ist die folgende PDF herunterzuladen und den Inhalt ebenfalls in ein entsprechendes Tool zu kopieren: REST-API-Swagger-v1.15.0.pdf