API-v1: Wie setzt ihr diese ein? Was wird davon wirklich genutzt?
IT swiss unihockey
Hallo zusammen
Wie viele von euch wohl wissen, wollen wir unsere erste API (nachfolgend API v1 genannt), https://api.swissunihockey.ch/, schon lange abschalten.
Wie wir eindeutig von vielen Seiten vernommen haben, wird die API bisweilen rege genutzt und es existieren momentan scheinbar keine Alternativen.
Das soll sich ändern.
Die API v1 wird durch eine neue API,
im weiteren API v3 genannt, abgelöst. Wir sind momentan in der
Konzeption (einige Teile wurden auch schon nachgebaut), für welche wir eure Bedürfnisse kennenlernen wollen.
Ziel ist es, mit möglichst wenig Geld und Zeit möglichst viel herauszuholen - das geht dann gut, wenn wir wissen, was ihr mit der API macht.
Folgende Rahmenbedingungen stehen bereits fest:
* Die API v3 ist eine REST-API.
* Die Datenstruktur folgt https://jsonapi.org/ - ihr müsst also kein Tabellen-JSON auseinandernehmen um damit zu arbeiten.
Inhaltlich werden wir uns an den Ergebnissen der Umfrage hier orientieren. Wir bitten euch, uns folgendes mitzuteilen:
* Wo verwendet ihr die API momentan?
* Gibt's eine URL zu eurer Webseite, App, etc?
* Könnt ihr kurz beschreiben, welche Daten ihr abfragt und was ihr damit Daten macht (z.B. "Ich lese die letzten Spiele meines Teams aus, um auf der Webseite...")?
* Was sind eure Datenquellen? API v1, Table API?
* Gäbe es interessante Informationen, an die ihr über die momentan verfügbaren APIs nicht herankommt?
* Aufgrund von wechseln in der IT kennt von uns niemand die API v1 so richtig gut. Wer uns also auch auflisten mag, welche Endpunkte der APIv1 er verwendet:
Das hilft uns sicher, beim konzipieren weniger zu übersehen.
Aus dem Bild, das sich hier ergibt, hoffen wir, die richtigen Funktionalitäten für eine erste Version der API priorisieren zu können.
Ihr dürft eure Rückmeldungen gerne an i...@swissunihockey.ch stellen oder diesen Beitrag kommentieren.
Ich danke euch vielmals für eure Unterstützung und wünsche euch eine gute restliche Woche!
Sportliche Grüsse
Curdin
Bert Hofmänner
clubs/444
clubs/444/teams
teams/409379/registrations
teams/409379/games
teams/409379/registrations
teams/409379/table
games/search
gyms/41212
leagues/114/groups
leagues/114/groups/4/games
leagues/114/groups/4/table
Fabian von Allmen
Hallo Curdin
Bert hat schon recht, es wird wohl ziemlich alles von der API V1 verwendet, was irgendwie verfügbar ist. Wir benutzen zwar keine Club Endpunkte, dafür ergänzend zur Liste von Bert die Endpunkte teams/search oder games/<id>.
Was ich an dieser Stelle noch anmerken möchte, ist dass die Endpunkte wohl da und dort nicht «nur» für die Website verwendet werden. Wir generieren daraus, z.B. auch Unterlagen für die Trainer/Eltern und haben eine volle Integration in unsere Präsenzkontrolle, die dann schlussendlich für die J+S Abrechnung benötigt wird. Für unsere internen Prozesse ist es also ziemlich entscheiden, dass wir eine zuverlässige Schnittstelle haben.
Besten Dank und Gruss
Fabian
| Fabian von Allmen / Vize-Präsident UHC Wehntal Regensdorf
|
--
Sie erhalten diese Nachricht, weil Sie in Google Groups E-Mails von der Gruppe "Swiss Unihockey Webmaster" abonniert haben.
Wenn Sie sich von dieser Gruppe abmelden und keine E-Mails mehr von dieser Gruppe erhalten möchten, senden Sie eine E-Mail an swissunihockey-web...@googlegroups.com.
Weitere Optionen finden Sie unter https://groups.google.com/d/optout.
Martin Oberhänsli
Wenn Sie sich von dieser Gruppe abmelden und keine E-Mails mehr von dieser Gruppe erhalten möchten, senden Sie eine E-Mail an swissunihockey-webmaster+unsub...@googlegroups.com.
IT swiss unihockey
Danke für eure Feedbacks hier und die Feedbacks per Mail.
In der erwähnten Gruppe lassen sich aber schon sehr viele Infos finden. Werde diese beim Erstellen der Anforderungen natürlich berücksichtigen.
Am Mittwoch, 7. November 2018 14:04:53 UTC+1 schrieb IT swiss unihockey:
tho...@treuthardt.ch
Mit etwas Verspätung hier noch unser Feedback zur Benützung der API v1 bei
den folgenden 5 Zuger Vereine:
- Zug United (http://www.zugunited.ch/)
- Zuger Highlands Floorball http://zugerhighlands.ch/
- UHC Zugerland (http://www.uhczugerland.ch/)
- UHC Astros Rotkreuz (http://www.astros.ch/)
- UHC Einhorn Hünenberg (http://www.uhceinhorn.ch/)
Wir verwenden die folgenden Endpoints der API V1:
- GET teams/{teamid}/games
- GET teams/{teamid}/table
- GET teams/{teamid}/registrations
- GET leagues/{leaguecode}/groups/{group}/games
- GET games/{gameid}
- GET clubs/{clubid}/teams
Wir verwenden die API v1 primär um Spielbetriebsdaten (inkl. Cup) auf den
Webseiten einzubinden. Wir speichern die Spieldaten (geplante und gespielte
Partien) und die aktuellen Platzierungen unserer Teams in einem definierten
Intervall in unserer DB. Diese Daten benötigen wir um effizient diverse
Funktionen umsetzen zu können. Z.B. Der Trend bei der Tabellenplatzierung
oder das manuelle Eintragen/Bearbeiten eines Spielresultats via unsere Admin
Console.
Wie auch schon in einem Feedback Email geschrieben wurde, ist es für uns
zentral, dass die via API zurückgelieferten Entitäten (Spiel, Teams, Clubs,
etc.) eine eindeutige ID beinhalten.
Wenn ihr jetzt an der API v3 arbeitet, wie sieht denn eure Roadmap bezüglich
"API v2" aus. Wird diese parallel zu v3 betrieben?
Gruss Thomas Treuthardt
Sie erhalten diese Nachricht, weil Sie Mitglied der Google
Groups-Gruppe "Swiss Unihockey Webmaster" sind.
dieser Gruppe erhalten möchten, senden Sie eine E-Mail an
Weitere Optionen: https://groups.google.com/d/optout
Robert Stucki
IT swiss unihockey
Ich freue mich über eures Feedback! Wir werden immer wieder informieren, wenn etwas umgesetzt ist und auf der API-v3 läuft. Wir versuchen ständig daran zu arbeiten (nebst den anderen Projekten) und hier somit nun einmal wirklich vorwärts zu kommen.
Überblick
Primärer Usecase scheint die Frage “Wo spielen die Teams unseres Clubs gegen wen, und mit welchen Resultaten?”. Dieser bietet sich an, um eine erste Version der API bereitzustellen.
Beteiligte Domänenobjekte
Fett geschriebene Objekte sollen in der Iteration 1 über einen eigenen Endpunkt exponiert werden.
- Saison season
- Verein club
- Team team
- Spiel game
- Halle gym
Beispiel-Usecases
- Team finden
- Verein finden
- Was sind die nächsten 5 Spiele eines Teams
- Was sind die nächsten Heimspiele eines Teams
- Was waren die Resultate der letzten Spiele eines Teams
- Was waren die Resultate der Spiele eines Vereins in der letzten Saison
- Wo finden die nächsten Spiele eines Teams statt
Endpoints
Unter
/api/v3/:
games/
- Filter
- Heim-, Auswärtspiele
- Spielstatus (läuft, gespielt, …)
- Datum
- Saison
- Inklusive Relation
game - gymteams/
- Filter
- Name
teams/games
- Inklusive Relation
game - gymclubs/
- Filter
- Name
clubs/teamsclubs/games
- Inklusive Relation
game - team- Inklusive Relation
game - gymBemerkung: Die Funktionalität der bestehenden API-v1-Such-Endpunkte wie
games/searchsoll durch Filter auf den v3-Collection-Endpunktengames/etc. bereitgestellt werden.Ressourcen
Grundsätzliches
Wir trauen uns zu, die meisten wichtigen Attribute einer Ressource selbst zu identifizieren. Das einfachste ist wohl, wenn ihr als Community nach der Liveschaltung einer ersten Version Feedback gebt, was noch fehlt.
game
Wettkampfinfo-Attribute
In der ersten Iteration werden wettkampbezogene Infos zu Spielen nicht als Ressourcen abgebildet (siehe Danger Zone). Die relevanten Infos werden unstrukturiert angeboten und können somit zumindest zur Darstellung verwendet werden. Wer diese Infos parst und darauf weitere Logik basiert, tut dies auf eigene Gefahr. Beispiele, was damit gemeint ist:
- Sich darauf verlassen, dass NLA-Spiele immer einen
championship_textmit dem Wert Herren NLA haben- Spiele aufgrund
championship_detail_textnach Gruppe sortieren und weiterverarbeitenMeisterschaftsspiele
championship_text: z.B Herren NLAchampionship_detail_text: z.B Gruppe 1Turnierspiele
championship_text: z.B Ligacup Herrenchampionship_detail_text: z.B Halbfinalsgym
Wird Adresse und Koordinaten einer Halle beinhalten.
team
club
Danger zone
Kontext für Interessierte: Momentan teilen sich vier verschiedene IT-Systeme (Portal, API v1, Verbandslösung, Business Server) eine Datenbank, welche aufgrund der engen Kopplung jedes Systems an die DB und fehlen jeglicher separation of concerns nicht mehr ohne unvertretbaren Aufwand verändert werden kann. Verschiedene Teile des Datenbankdesigns weisen erhebliche Mängel auf, diese können aufgrund der vorherrschenden Situation aber nicht behoben werden. Das Problem soll gelöst werden, indem die bestehenden Systeme schrittweise in ein einziges System migriert werden.
Es gibt daher einige Infos in der Datenbank, welche vorerst nur mit erheblichem Aufwand seitens swiss unihockey (um das Verhalten der API während der nötigen Aufräumarbeiten gleich zu halten) oder der Community (um die Applikationen welche die Schnittstelle verwenden fortlaufend an eine ändernde API anzupassen) via Schnittstelle angeboten werden können. Es ist wohl für alle Seiten am nervenschonendsten, wenn wir vorerst ohne diese auskommen und gezielt dort Kompromisse eingehen, wo eine fehelende Information auf sehr grosse Nachfrage trifft.
Folgende Konzepte werden im Sportjargon, von der Verbandslösung und vom Portal separat ausgelegt und vom Business Server auf nochmals andere Konzepte abgebildet. Wir werden sie nicht einfach 1:1 exponieren, bevor klar ist, wie das bestehende Wirrwarr aufgelöst werden soll.
- Liga
- Meisterschaft
- Turnier
- Spielklasse
- Gruppe
- Runde
Die folgenden Konzepte sind in der Datenbank unzulänglich modelliert. Sie sollen nicht in der vorhandenen Struktur exponiert werden, damit wir das bestehende Datenbankdesign nicht noch stärker zementieren. Es generiert am wenigsten Aufwand, die API nach den Aufräumarbeiten nach dem neuen Design zu richten.
- Ereignisse
- Lizenzen
- Die Beziehung Spieler - Lizenz - Spiel
- Die Beziehung Spieler - Lizenz - Verein
Ein weiterer Sonderfall ist die Tabelle, welche zumindest zur Darstellung auf Webseiten weiterhin via API v2 angeboten wird. Für diese existieren momentan die Portal und API-v1-Implementationen (eine Mischung aus u.a. DB-Views und einem über 4000 Zeichen langen SQL-Query) und die API-v2-Implementation (eine Mischung aus DB-Triggers, redundant geführten Aggretationstabellenm einem 24/7 laufenden Job, der das ganze nachführt und einem selbstgebauten ORM und View-Layer, um die Informationen darzustellen). Hier ohne vorheriges Aufräumen eine weitere Implementation hinzuzufügen, scheint nicht ratsam.
Martin Oberhänsli
cYr
Am Montag, 21. Januar 2019 15:26:19 UTC+1 schrieb IT swiss unihockey:
Sven Eisenring
Adi Henggeler
Seit der letzten offiziellen Info ist nun bald wieder ein Jahr
vergangen. Was ist der aktuelle Stand mit der API V1 bzw. V3.
Gibt es da News, wann diese abgestellt resp. in Betrieb genommen werden?
Was passiert mit der API V2? Wird diese bei Inbetriebnahme von V3 auch
abgestellt oder bleibt diese parallel bestehen?
Für eine klärende Stellungnahme wären Dir wohl alle Webmaster dankbar.
Gruess
Adi
Am 21.01.2019 um 15:26 schrieb IT swiss unihockey:
> Hallo zusammen
>
> Untenstehend findet ihr einen Überblick über die anstehenden Arbeiten
> und wie, was umgesetzt werden muss und wo unsere Problemstellungen
> begraben liegen.
> Ich freue mich über eures Feedback! Wir werden immer wieder informieren,
> wenn etwas umgesetzt ist und auf der API-v3 läuft. Wir versuchen ständig
> daran zu arbeiten (nebst den anderen Projekten) und hier somit nun
> einmal wirklich vorwärts zu kommen.
>
> Liebe Grüsse
> Curdin
>
>
> Überblick
>
> Primärer Usecase scheint die Frage “Wo spielen die Teams unseres
> Clubs gegen wen, und mit welchen Resultaten?”. Dieser bietet sich
> an, um eine erste Version der API bereitzustellen.
>
>
> Beteiligte Domänenobjekte
>
> eigenen Endpunkt exponiert werden.
>
> * Saison /season/
> * *Verein* /club/
> * *Team* /team/
> * *Spiel* /game/
> * Halle /gym/
>
>
> Beispiel-Usecases
>
> * Team finden
> * Verein finden
> * Was sind die nächsten 5 Spiele eines Teams
> * Was sind die nächsten Heimspiele eines Teams
> * Was waren die Resultate der letzten Spiele eines Teams
> * Was waren die Resultate der Spiele eines Vereins in der letzten
> Saison
> * Wo finden die nächsten Spiele eines Teams statt
>
>
> Endpoints
>
> Unter |/api/v3/|:
>
> * |games/|
> o Filter
> + Heim-, Auswärtspiele
> + Spielstatus (läuft, gespielt, …)
> + Datum
> + Saison
> o Inklusive Relation |game - gym|
> * |teams/|
> o Filter
> + Name
> * |teams/games|
> o Inklusive Relation |game - gym|
> * |clubs/|
> o Filter
> + Name
> * |clubs/teams|
> * |clubs/games|
> o Inklusive Relation |game - team|
> o Inklusive Relation |game - gym|
> Bemerkung: Die Funktionalität der bestehenden API-v1-Such-Endpunkte
> wie |games/search| soll durch Filter auf den
> v3-Collection-Endpunkten |games/| etc. bereitgestellt werden.
>
>
> Ressourcen
>
>
> Grundsätzliches
>
> Wir trauen uns zu, die meisten wichtigen Attribute einer Ressource
> selbst zu identifizieren. Das einfachste ist wohl, wenn ihr als
> Community nach der Liveschaltung einer ersten Version Feedback gebt,
> was noch fehlt.
>
>
> game
>
>
> Wettkampfinfo-Attribute
>
> In der ersten Iteration werden wettkampbezogene Infos zu Spielen
> zumindest zur Darstellung verwendet werden. Wer diese Infos parst
> und darauf weitere Logik basiert, tut dies auf eigene Gefahr.
> Beispiele, was damit gemeint ist:
>
> |championship_text| mit dem Wert /Herren NLA/ haben
> * Spiele aufgrund |championship_detail_text| nach Gruppe sortieren
> und weiterverarbeiten
>
>
> Meisterschaftsspiele
>
> * |championship_text|: z.B /Herren NLA/
> * |championship_detail_text|: z.B /Gruppe 1/
>
>
> Turnierspiele
>
> * |championship_text|: z.B /Ligacup Herren/
> * |championship_detail_text|: z.B /Halbfinals/
>
> gym
>
> Wird Adresse und Koordinaten einer Halle beinhalten.
>
>
> team
>
>
>
> club
>
> *
>
> Danger zone
>
> Kontext für Interessierte: Momentan teilen sich vier verschiedene
> IT-Systeme (Portal, API v1, Verbandslösung, Business Server) eine
> Datenbank, welche aufgrund der engen Kopplung jedes Systems an die
> DB und fehlen jeglicher separation of concerns nicht mehr ohne
> unvertretbaren Aufwand verändert werden kann. Verschiedene Teile des
> Datenbankdesigns weisen erhebliche Mängel auf, diese können aufgrund
> der vorherrschenden Situation aber nicht behoben werden. Das Problem
> soll gelöst werden, indem die bestehenden Systeme schrittweise in
> ein einziges System migriert werden.
>
> Es gibt daher einige Infos in der Datenbank, welche vorerst nur mit
> erheblichem Aufwand seitens swiss unihockey (um das Verhalten der
> API während der nötigen Aufräumarbeiten gleich zu halten) oder der
> Community (um die Applikationen welche die Schnittstelle verwenden
> fortlaufend an eine ändernde API anzupassen) via Schnittstelle
> angeboten werden können. Es ist wohl für alle Seiten am
> nervenschonendsten, wenn wir vorerst ohne diese auskommen und
> gezielt dort Kompromisse eingehen, wo eine fehelende Information auf
> sehr grosse Nachfrage trifft.
>
> Folgende Konzepte werden im Sportjargon, von der Verbandslösung und
> vom Portal separat ausgelegt und vom Business Server auf nochmals
> andere Konzepte abgebildet. Wir werden sie nicht einfach 1:1
> exponieren, bevor klar ist, wie das bestehende Wirrwarr aufgelöst
> werden soll.
>
> * Meisterschaft
> * Turnier
> * Spielklasse
> * Gruppe
> * Runde
> Die folgenden Konzepte sind in der Datenbank unzulänglich
> modelliert. Sie sollen nicht in der vorhandenen Struktur exponiert
> werden, damit wir das bestehende Datenbankdesign nicht noch stärker
> zementieren. Es generiert am wenigsten Aufwand, die API nach den
> Aufräumarbeiten nach dem neuen Design zu richten.
>
> * Lizenzen
> * Die Beziehung Spieler - Lizenz - Spiel
> * Die Beziehung Spieler - Lizenz - Verein
>
> Ein weiterer Sonderfall ist die *Tabelle*, welche zumindest zur
> diese existieren momentan die Portal und API-v1-Implementationen
> (eine Mischung aus u.a. DB-Views und einem über 4000 Zeichen langen
> SQL-Query) und die API-v2-Implementation (eine Mischung aus
> DB-Triggers, redundant geführten Aggretationstabellenm einem 24/7
> laufenden Job, der das ganze nachführt und einem selbstgebauten ORM
> und View-Layer, um die Informationen darzustellen). Hier ohne
> vorheriges Aufräumen eine weitere Implementation hinzuzufügen,
> scheint nicht ratsam.
>
> Gruppe "Swiss Unihockey Webmaster" abonniert haben.
> dieser Gruppe erhalten möchten, senden Sie eine E-Mail an
> swissunihockey-web...@googlegroups.com