The Web Service API of Web Calendar (before 2011)

Overview

Using the web service API, the events and appointments maintained by means of Web Calendar can be published. On the one hand, the data can be published once or periodically in order to subsequently process it using other systems. On the other hand, the events and appointments data can be dynamically included into web pages by integrating the web service into a portal.

The web service only supports read access to the Web Calendar. To be able to use the functions of the web service, a so-called API key is required which needs to be specified whenever the web service is accessed. Each key is valid only for a particular customer of the Web Calendar. Furthermore, the web service request must originate from an authorized IP address. If questions concerning authorization and registration arise, please contact our Customer Support.

The web service has two interfaces, a rather simple one based on so-called RESTful resources, and another one based on SOAP.

RESTful Resources

RESTful Resources are a simple method for making a web service available to the clients without having to provide special client software. By means of the web service, two resources can be accessed, events and categories. Since only read access is possible, only one operation can be performed for each resource, the index operation. It can be initiated by means of an HTTP GET request to the resource URL.

If you have got a valid API key, open the following URL in your web browser:

http://host.domain/webservice/instance1/cal1/categories?api_key=xxxxx

In the URL above, replace host.domain with the host name that was registered for you, instance1 with your client name, and cal1 with the name of one of your calendars. This will return the list of categories you defined for the specified calendar. If your web browser is able to display XML data, the result can be viewed instantly. Alternatively, you can also use a command-line tool such as curl to access the resource:

curl http://agenda.infopark.de/webservice/wstest/cal/categories?api_key=webservicetestapikey

For most modern software programming and portal frameworks, suitable modules for performing the corresponding HTTP requests exist.

The XML data returned by the web service can easily be read using an XML parser and then be processed as desired. The format of the XML data is RelaxNG. For an introduction to RelaxNG please refer to http://relaxng.org/tutorial-20011203.html.

SOAP Interface

For a general description of the functions and the data types used, please refer to the Events Resource Reference and the Categories Resource Reference. The SOAP interface with its access points, the functions, and the data types used is described in a WSDL file. The WSDL file can be accessed via the URL http://agenda.infopark.de/soap_webservice/service.wsdl.

The SOAP interface provides the following four functions:

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
)

The FindEvents function searches for events that match the specified search criteria. The individual parameters and the result are described in the Events Resource Reference. The function returns a list of 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
)

The FindEventsWithTotal function searches events that match the specified search criteria. For a description of the individual parameters, please refer to the Events Resource Reference. The function is identical to FindEvents. However, it additionally determines the total numer of events that match the search criteria. The function result is a WebserviceEventsWithTotal structure which consists of a list of events and the total number of events found.

WebserviceEvent GetEvent(
  string api_key, 
  string instance_name, 
  string calendar_name, 
  int id
)

The GetEvent function returns the event with the specified unique key, if it exists and has been released for publication. The individual parameters and the result are described in the Events Resource Reference. The function returns a list of events.

WebserviceCategory[] FindCategories(
  string api_key, 
  string instance_name, 
  string calendar_name
)

The FindCategories function returns the categories defined for the specified calendar. The individual parameters and the result are described in the Categories Resource Reference. This function returns a list of categories.