====== API für Datenbezüger ======

Der Minasa-Datenhub liefert die Basis zum Austausch von Event-Daten im Minasa-Schema. Interessierte Bezüger können über eine API die gewünschten Daten abrufen.

===== Abfragen =====

Zum Download der Daten wird ein API-Key benötigt, der bei Saiten bestellt werden kann.

^System^URL^Methode|
|Minasa Datenhub LIVE|[[https://azizi.2mp.ch/export/events/v/1|https://azizi.2mp.ch/export/events/v/1]]|GET|
|Testsystem|[[https://azizi.nilkream.ch/export/events/v/1|https://azizi.nilkream.ch/export/events/v/1]]|GET|

==== AUTHORIZATION ====

Die Authorisierung erfolgt mit API-Key im HTTP-Header nach folgendem Schema:

^HTTP Header^auth-scheme^authorization-parameters|
|Authorization|apikey|API-KEY|

Beispiel:
<code>

     curl \
      --location 'https://azizi.nilkream.ch/export/events/v/1' \
      --header 'Authorization: apikey XYZ01234...ABC'

</code>




===== Format =====

Daten werden im XML-Format ausgeliefert. Elemente, die HTML-Formatierung enthalten können sind als [[https://de.wikipedia.org/wiki/CDATA|CDATA-Abschnitt ]]ausgewiesen.

Bilder werden als Download-URL verlinkt und sind vom empfangenden System separat herunterzuladen.

===== Filter =====

Der Datenhub stellt verschiedene Filter zur Verfügung, die als HTTP-Query-Parameter übergeben werden:

^Parameter^Beschreibung^Beispiele^Erläuterungen|
|''category'' |Veranstaltungs-Kategorie, Rubrik|''category=Literatur,Kunst'' |gültige Kategorie gemäss [[:datenhub:schema|Minasa-Schema]]|
|''zip'' |PLZ des Veranstaltungsorts|''zip=9000,9001,9004,9006,9007,9008,9009,9010,9011,9012,9013,9014,9015,9016'' |Bsp. für gesamte Stadt St. Gallen|
|''canton'' |Kanton des Veranstaltungsorts|''canton=AI,AR'' |Bsp. für beide Appenzell|
|''dataProviderIncluded'' |nur diese Datenlieferanten|''dataProviderIncluded=0187dc91-efa5-7e6f-a417-5a9bb49bb64e'' |GUIDs von Datenlieferanten werden vom Datenhub fix vergeben|
|''dataProviderExcluded'' |ausser diese Datenlieferanten|''dataProviderExcluded=0187dc91-efa5-7e6f-a417-5a9bb49bb64e'' |GUIDs von Datenlieferanten werden vom Datenhub fix vergeben|

Werden mit der Anfrage keine Filter mitgeschickt, liefert der Datenhub alle aktuellen, verfügbaren Event-Daten aus.

Verschiedene Filter können in derselben Abfrage kombiniert werden.

Beispiel:
<code>

     curl \
      --location 'https://azizi.nilkream.ch/export/events/v/1?canton=AI,AR&category=Literatur,Kunst' \
      --header 'Authorization: apikey XYZ01234...ABC'

</code>

===== Einschränkungen =====

Der Datenhub importiert in der Regel einmal pro Tag Event-Daten aus direkt-angebundenen externen Datenbanken (i.d.R. Websites von Veranstaltern) und aus den verbundenen Minasa-Systemen.

Die Event-Daten sind **einmal täglich** abzurufen und für die Weiterverabeitung auf einem Server beim Datenbezüger zu speichern. Downloads werden überwacht und blockiert, falls pro Zeiteinheit mehr als eine definierte Anzahl von Zugriffen mit demselben API-Key erfolgt.