SAMS API-Hub

- Der nachfolgend beschriebene Dienst wird bis auf Weiteres nur vorläufig in diesem Umfang zur Verfügung gestellt. Eine durchgängige Verfügbarkeit wird ausdrücklich NICHT gewährleistet. Bei allgemeinen (nicht technischen) Rückfragen wenden Sie sich bitte an 2ndlevel@volleyball-it.de -

Das SAMS API-Hub ist ein zentraler Schnittstellendienst zum Abruf öffentlich zugänglicher Daten aller SAMS-Installation. Zur Verwendung ist ein gültiger und für das Hub freigeschalteter SAMS-API-Key notwendig, aus dem einmalig ein Token zur Verwendung der Schnittstelle erzeugt wird. Die Schnittstellen basieren auf JSON und normalen HTTP-Get-Requests nach REST-Paradigma.

Datum- und Zeitangaben sind entsprechend ISO 8601 (s. http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTimeNoMillis() ) formatiert.

Folgende Schnittstellen sind verfügbar:

Authentifizierung (einmalig)

https://apihub.sams-server.de/token/<SAMS-API-Key>

Liefert ein dauerhaftes Zugriffstoken zur Verwendung der folgenden Schnittstellen. Das Token ist fest mit dem SAMS-API-Key verknüpft.

Datenabruf

Die GET-Schnittstellen für den Datenabruf sind alle nach folgenden Schemata aufgebaut:

• https://apihub.sams-server.de/<Token>/get/instances
  • Liefert eine Liste aller SAMS-Instanzen, die im API-Hub enthalten sind.
• https://apihub.sams-server.de/<Token>/get/<SamsXXX>/<Objekttyp>
  • Liefert eine Liste aller vorhandenen Objekte vom gegebenen Typ aus einer SAMS-Instanz
  • insbesondere zum Abruf einer Saisonübersicht mit allen Ligen und Wettbewerben (/get/SamsXXX/season)
• https://apihub.sams-server.de/<Token>/get/<UUID>
  • Gibt die Daten eines Objekts vom beliebigen Typ mit der gegebenen UUID zurück

Vorhandene Objekttypen sind:

• season
  • verfügbare Saisons mit Hierarchien und Spielrunden
  • Hierarchien entsprechend der Sortierung im Verband
  • Der Wert indention entspricht der Anzahl der übergeordneten Hierarchien
  • Eine Auflistung der Hierarchien selber Reihenfolge wie in der Schnittstelle, eingerückt um indention Abstände, entsprecht der Darstellung im SAMS-Administrationsbereich
• matchSeries
  • Spielrunden (Ligen und Wettbewerbe) mit Spielplänen und Mannschaften
• team
  • Mannschaften mit Mannschaftslisten
• club
  • Vereine

Beispiele

Für die Beispiele wird die fiktive SAMS-Instanz "SamsBeispiel" und der fiktive Api-Key "ac67ddc0-6176-11e7-907b-a6006ad3dba0" und Zugriffs-Token "3c982513-d1fb-425a-aa14-621c66988e99" verwendet.

Mannschaftsspielplan

1. Einmalig: Erzeugen des Zugriffs-Tokens:
   • https://apihub.sams-server.de/token/ac67ddc0-6176-11e7-907b-a6006ad3dba0
   • Der Zugriffstoken "3c982513-d1fb-425a-aa14-621c66988e99" wird zurück gegeben
2. Einmalig: Finden der Mannschafts-UUID
   • Spielrunden-UUID aus https://apihub.sams-server.de/3c982513-d1fb-425a-aa14-621c66988e99/get/SamsBeispiel/season heraussuchen
     • Beispiel: 4d44e42c-75e2-4f45-856b-f57717708644
   • Mannschafts-UUID aus Spielrunden-Daten https://apihub.sams-server.de/3c982513-d1fb-425a-aa14-621c66988e99/get/4d44e42c-75e2-4f45-856b-f57717708644 heraussuchen
     • Beispiel: 5eed6bbb-4324-4448-9d77-dfc18fd1599c
3. Die URL zum Abruf der Mannschaftsdetails für die jeweilige Saison lautet https://apihub.sams-server.de/3c982513-d1fb-425a-aa14-621c66988e99/get/5eed6bbb-4324-4448-9d77-dfc18fd1599c