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
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.
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.