Das Web-Service-API des Web Calendars (vor 2011)

Überblick

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.

RESTful Resources

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.

SOAP-Interface

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.