Mit dem Web-Service-API können die im Web Calendar verwalteten Veranstaltungen und Termine publiziert werden. Es ist einerseits möglich, die Daten einmalig oder periodisch zu exportieren, um sie dann in anderen Systemen weiterzuverarbeiten. Andererseits kann man die Daten der Veranstaltungen und Termine dynamisch in Webseiten integrieren, indem man den Web-Service direkt in ein Portal einbindet.
Der Web-Service unterstützt nur lesende Zugriffe auf den Web Calendar. Um die Funktionen des Web-Services zu nutzen, benötigt man einen sogenannten API-Key. Dieser muss bei allen Zugriffen auf den Web-Service angegeben werden. Er gilt nur für jeweils einen bestimmten Kunden des Web Calendars. Ferner kann der Web-Service nur von autorisierten IP-Adressen verwendet werden. Bei Fragen zu Autorisierung und Freischaltung wenden Sie sich bitte an unseren Support.
Der Web-Service hat zwei Interfaces, ein sehr einfaches auf der Basis sogenannter RESTful Resources und ein zweites auf der Basis von SOAP.
Bei den sogenannten RESTful Resources handelt es sich um ein sehr einfaches Verfahren, mit dem ein Web-Service ohne spezielle Software auf der Client-Seite genutzt werden kann. Über den Web-Service kann auf zwei Ressourcen zugegriffen werden, die Termine und die Kategorien. Da ausschließlich Lese-Zugriffe unterstützt werden, ist auf jeder Ressource nur eine Operation, die "index"-Operation möglich. Diese wird jeweils durch einen HTTP-GET-Request auf die Resource-URL ausgeführt.
Falls Sie über einen gültigen API-Key verfügen, können Sie die folgende URL mit Ihrem Web-Browser abfragen:
http://host.domain/webservice/instance1/cal1/categories?api_key=xxxxx
Ersetzen Sie in der obigen URL host.domain
durch den für Sie freigeschalteten
Hostnamen, instance1
durch Ihren Mandanten-Namen und cal1
durch den
Namen eines Ihrer Kalender. Sie erhalten dann die Liste der von
Ihnen für diesen Kalender definierten Kategorien.
Wenn Ihr Web-Browser in der Lage
ist, XML-Daten darzustellen, können Sie das Ergebnis sofort betrachten.
Alternativ können Sie auch mit einem Command-Line-Tool wie
curl
auf die Ressource zugreifen:
curl http://agenda.infopark.de/webservice/wstest/cal/categories?api_key=webservicetestapikey
In den meisten modernen Programmier- und Portal-Frameworks gibt es passende Module, mit denen man leicht die entsprechenden HTTP-Zugriffe ausführen kann.
Die vom Web-Service zurückgegebenen XML-Daten können mit ein XML-Parser leicht eingelesen und für die gewünschten Zwecke weiterverarbeitet werden. Die zurückgegebenen XML-Daten sind im Format RelaxNG beschrieben. Eine Einführung zu RelaxNG befindet sich unter der Adresse http://relaxng.org/tutorial-20011203.html.
Eine allgemeine Beschreibung der Funktionen und der verwendeten Datentypen für die Parameter und die Rückgabewerte finden Sie in der Events-Ressource-Referenz und der Categories-Ressource-Referenz. Das SOAP-Interface mit den Zugriffspunkten, den Funktionen und den verwendeten Datentypen ist in einer WSDL-Datei beschrieben. Die WSDL-Datei kann über http://agenda.infopark.de/soap_webservice/service.wsdl erreicht werden.
Das SOAP-Interface stellt die folgenden vier Funktionen zur Verfügung:
WebserviceEvent[] FindEvents( string api_key, string instance_name, string calendar_name, string where, string what, time from, time to, string category, int offset, int limit )
Die Funktion FindEvents
sucht Events entsprechend den
angegebenen Suchkriterien. Die einzelnen Parameter und das Ergebnis sind in
der Events-Ressource-Referenz beschrieben. Das Ergebnis der Funktion ist eine
Liste von Events.
WebserviceEventsWithTotal FindEventsWithTotal( string api_key, string instance_name, string calendar_name, string where, string what, time from, time to, string category, int offset, int limit )
Die Funktion FindEventsWithTotal
sucht Events entsprechend der
angegebenen Suchkriterien. Die einzelnen Parameter und das Ergebnis sind
in der
Events-Ressource-Referenz beschrieben. Die Funktion ist identisch
mit der Funktion FindEvents
. Sie ermittelt jedoch zusätzlich die
Gesamtzahl der Events, die die angegebenen Suchkriterien erfüllen. Das
Ergebnis der Funktion ist eine WebserviceEventsWithTotal
-Struktur, die
eine Liste von Events und die Gesamtzahl der gefundenen Events
enthält.
WebserviceEvent GetEvent( string api_key, string instance_name, string calendar_name, int id )
Die Funktion GetEvent
liefert als Ergebnis den Event mit dem
angegebenen eindeutigen Schlüssel, falls er existiert und zur
Veröffentlichung freigegeben ist. Die einzelnen Parameter und das Ergebnis
sind in der Events-Ressource-Referenz beschrieben.
WebserviceCategory[] FindCategories( string api_key, string instance_name, string calendar_name )
Die Funktion FindCategories
liefert die für den angegebenen
Kalender definierten Kategorien. Die einzelnen Parameter und das Ergebnis
sind in der Categories-Ressource-Referenz beschrieben. Das Ergebnis dieser
Funktion ist eine Liste von Categories.