Semantic Annotation of Web APIs with SWEET Maria Maleshkova, Carlos Pedrinaci, John Domingue Knowledge Media Institute (KMi) The Open University, Milton Keynes, United Kingdom {m.maleshkova, c.pedrinaci, j.b.domingue}@open.ac.uk Abstract. Recently technology developments in the area of services on the Web are marked by the proliferation of Web applications and APIs. The development and evolution of applications based on Web APIs is, however, hampered by the lack of automation that can be achieved with current technologies. In this paper we present SWEET– Semantic Web sErvices Editing Tool– a lightweight Web application for creating seman- tic descriptions of Web APIs. SWEET directly supports the creation of mashups by enabling the semantic annotation of Web APIs, thus con- tributing to the automation of the discovery, composition and invocation service tasks. Furthermore, it enables the development of composite SWS based applications on top of Linked Data. 1 Introduction Since the advent of Web service technologies, research on semantic Web services (SWS) has been devoted to reduce the extensive manual effort required for ma- nipulating Web services. The main idea behind this research is that tasks such as the discovery, negotiation, composition and invocation of Web services can have a higher level of automation, when services are enhanced with semantic descriptions of their properties. Recently, technology developments in the area of services on the Web are marked by the proliferation of Web applications and APIs. The development and evolution of applications based on Web APIs is, however, hampered by the lack of automation that can be achieved with current technologies. Research on semantic Web services is therefore trying to adapt the principles and technologies that were devised for traditional Web services, to deal with this new kind of services. Web APIs are characterized by their relative simplicity and their natural suitability for the Web, which is indeed closely related to the growing popular- ity and use of Web 2.0 technologies. Many Web 2.0 applications like Facebook, Google, Flickr and Twitter offer easy-to-use Web APIs, which not only provide simple access to different resources but also enable combining heterogeneous data coming from diverse sources, in order to create mashups. However, despite their success, Web APIs are currently facing the same limitations that were identified for traditional Web service technologies and present even further difficulties. In particular, as opposed to WSDL services, there is no widely accepted structured language for describing Web APIs, even though there are some initial approaches in the area [8], [9]. As a consequence, in order to use Web APIs, developers are obliged to manually locate, retrieve, read and interpret heterogeneous documen- tations commonly given in HTML, and subsequently develop custom tailored software that is able to invoke and manipulate these Web APIs. In order to support the creation of mashups and the more automated han- dling of Web APIs in general, we have developed SWEET1 – Semantic Web sErvices Editing Tool. SWEET is a lightweight Web application, which requires no installation and can be invoked directly in the Web browser. It is realized by using JavaScript and ExtGWT2 and supports the development of mashups based on linked open data and services, by enabling the creation of semantic descriptions of Web APIs. In particular, SWEET can be used to annotate Web APIs, which results in semantic descriptions that are amenable to automated reasoning and can therefore support a higher level of automation during the discovery, composition and invocation of Web APIs. As a consequence SWEET contributes to better supporting the creation of mashups and applications based on linked open data and Web APIs. The remainder of this paper is structured as follows: Section 2, provides an overview of the existing formalisms for the semantic description of Web APIs, while Section 3 exemplifies how semantically annotated Web APIs can contribute to the scalability and flexibility of the creation of mashups. Section 4 introduces SWEET, including its components, functionalities and user support. An example for creating semantic descriptions of Web APIs is given in Section 5. Section 6 presents an overview of comparable tools, related formalisms and approaches. Finally, Section 7 presents future work that will be carried out and concludes the paper. 2 Semantic Annotation of Web APIs Recently, the world around services on the Web, thus far limited to “classical” Web services based on SOAP and WSDL, has significantly evolved with the proliferation of Web applications and APIs, often referred to as RESTful Web services [1], when conforming to the REST architectural style [2]. The majority of the Web API descriptions are usually given in the form of unstructured text in a Web page, which contains a list of the available operations, their URIs and parameters, expected output, error messages and an example. Since currently most Web applications and Web APIs rely only on HTML documentation, with no fixed structure or content, we use the hRESTS [3] microformat [4], which en- ables the creation of machine-processable descriptions on top of existing HTML descriptions. hRESTS contains only a few elements, is very lightweight and easy to use. Microformats, in general, facilitate the translation of the HTML tag structure into objects and properties, while hRESTS in particular, uses class and rel 1 http://sweetdemo.kmi.open.ac.uk/war/MicroWSMOeditor.html 2 ExtGWT is a Java library for building rich internet applications with Google Web Toolkit (GWT). http://extjs.com/products/gxt/ XHTML attributes to mark key service properties (see Listing 1.1), leaving the visualization of the HTML description unchanged. hRESTS introduces tags for marking the service description as a whole, the used HTTP method, the opera- tion with corresponding input and output, and the service or operation names in the form of labels. Therefore, hRESTS marks the key properties of the Web API and provides a machine-readable description based on the available HTML documentation. The result can be used as the basis for adding complementary information and annotations. We use MicroWSMO [5] for the semantic annotation of RESTful services, which enables the creation of SAWSDL-like [6] annotations. It has three main elements, which represent links to URIs of semantic concepts and data transfor- mations. The model tag indicates that the URI is a link to an ontology entity, while lifting and lowering point to links for lifting and lowering transforma- tions between the level of technical descriptions (for example XML, used as a data exchange format) and the level of semantic knowledge (for example RDF, used for semantic-based manipulation such as reasoning). The MicroWSMO mi- croformat is relatively simple but it provides all the elements necessary for at- taching semantic information to Web API descriptions. In summary, we use MicroWSMO and hRESTS, to support the automation of Web API-related tasks, such as discovery, composition and invocation. The here presented approach is very lightweight because it relies on the use of mi- croformats, which only enhance existing HTML descriptions with a few simple tags, without modifying the existing visualization. It only relies on the use of in- cremental extensions, which results in a low overhead of its uptake and practical use. In addition, the annotation process does not require extensive user training or ontology knowledge, and is very intuitive. In particular, SWEET supports users in creating semantic annotations of Web APIs by abstracting away from the technical details and assisting in the location of suitable domain ontologies from the Web. 3 Supporting the Creation of Mashups In this section we describe a data-oriented composition, i.e. a mashup, that we implemented in order to exemplify the importance of the semantic annotation of Web APIs for the creation of compositions, based on linked open data and Web APIs. The availability of linked open data, such as the one published by the open government data initiative3 , provides the foundation for the development of di- verse mashups, where distinct sources can be combined to provide added-value solutions. Moreover, these data compositions can be enhanced by integrating the existing Web APIs as additional data sources. As a result, Web applications can be created to display or synthesize linked open data and data retrieved through Web APIs. 3 http://data.gov.uk/ Undoubtedly such applications can be very useful and there are already a number of existing implementations, the most common ones probably being the visualization of data by using the Google Maps API. However, currently, a developer needs to manually search for suitable Web APIs, implement the data composition and realize its invocation. The result is a mashup based on open data and Web APIs. However, applications created in this way have very restricted potential when it comes to reusability, maintenance and extensibility. Fig. 1. Combining Local Schools Data with a Web API for Crime Statistics In order to enable the reusability of Web APIs within mashups and to add a higher level of automation to the composition process, we propose the use of semantic descriptions of Web APIs. Figure 1 visualizes a Web application im- plemented by combining open government data about schools in Milton Keynes with APIs for retrieving location-based crime statistic and visualizing it together in Google Maps. However, instead of hard-coding the implementation, we use the latitude and longitude as search parameters for finding relevant Web APIs. In this way, based on the semantic descriptions, we are able to discover and provide a set of services, which take as input latitude and longitude and return location-based information such as crime statistic or local businesses. In order to support the creation of semantic descriptions of Web APIs and contribute to the flexible and easier creation of mashups, we use SWEET. 4 SWEET SWEET (http://sweet.kmi.open.ac.uk/) is a Web application developed us- ing JavaScript and ExtGWT, which is started in a Web browser by calling the host URL. It implementation is mainly based on using scripting programming languages and is part of a fully-fledged framework supporting the lifecycle of services, particularly targeted at enabling the creation of semantic descriptions of Web APIs. SWEET takes as input an HTML Web page describing a Web API and offers functionalities, which enable users to annotate the service properties and to associate semantic information to them. In comparison to previously published versions of SWEET [16] this version of the tool has some additional features, is more stable, uses a new API of Watson for searching ontologies and has proven to support the creation of composite Web applications based on joining linked open data and semantically annotated Web APIs. As it can be seen in Figure 2, the architecture of SWEET consists of three main components, including the visualization component, the data preprocessing component and the annotations recommender. The annotations recommender assists the user in annotating a service by suggesting suitable annotations for the service as a whole (domain ontology recommendation) and for its individual properties. This component is still under development and will be available soon. The data preprocessing component implements functionalities for data prepara- tion for the visualization component, caching mechanisms and simple rule-based analysis. Fig. 2. SWEET Architecture The GUI of the visualization component is shown in Figure 3 and it has three main panels. The the HTML description of the Web API is loaded in the Navigator panel, which implements a reverse proxy [10] that enables the communication between the annotation functions and the HTML by rerouting all sources and connections from the original HTML through the Web application. The result is a local representation of the HTML, which is used as a basis for the annotation process. In this way, the HTML DOM can freely be manipulated and different HTML tags can be added by using functionalities of the Annotation Editor panel. The current status of the annotation is visualized in the form of a tree structure in the Semantic Description panel. It is implemented using the Model-View-Control architecture pattern [10], automatically synchronizing the visualization of the service annotation with an internal model representation, every time the user manipulates it. In addition to these three main panels, SWEET offers a number of supple- mentary useful functionalities. It guides the user thorough the process of marking service properties with hRESTS tags, by limiting the available tags depending on the current state of the annotation. This implements measures for reducing possible mistakes during the creation of annotations. In addition, based on the hRESTS tagged HTML, which provides the structure of the Web API, the user can link service properties to semantic content. This is done by selecting service properties, searching for suitable domain ontologies by accessing Watson [11] in an integrated way, and by browsing ontology information. In particular, Watson assist users in locating appropriate annotations and enables the accessing of ex- isting ontological data on the Web, in order to increase the level of reusability of services through ontology reuse. The search results include matching concepts, properties and instances from different ontologies. Based on this details the user can decide to associate a service property with particular semantic information by inserting a MicroWSMO model reference tag. Fig. 3. Inserting hRESTS tags with SWEET. SWEET effectively supports users in creating semantic descriptions of Web APIs by marking service properties, by searching for suitable ontologies, and by attaching semantic information. When the user completes the semantic annota- tion of the HTML description, the Web API annotation can be locally saved as annotated HTML or as extracted RDF. In addition, both the annotated HTML and the RDF can be directly published to the iServe4 [17] repository for seman- tic Web service descriptions. iServe can then be used to discover services, which can effectively be integrate in data mashups. 5 Annotation of Web APIs with SWEET This section exemplifies how SWEET supports each of the tasks along the pro- cess of creating semantic descriptions of Web APIs. SWEET takes as input the 4 http://iserve.kmi.open.ac.uk/ HTML Website describing the Web API and returns a semantically annotated version of the HTML or an RDF MicroWSMO description. In order to do this the user needs to complete the following four mains steps: 1. Identifying service properties by inserting hRESTS tags in the HTML service description. 2. Searching for domain ontologies suitable for annotating the service proper- ties. 3. Annotating service properties with semantic information. 4. Saving or exporting the annotated Web API. The first step can easily be completed by simply selecting the part of the HTML, which describes a particular service property, and double-clicking on the corre- sponding tag in the inset hTags pane (Figure 3). In the beginning, only the Service node of the hRESTS tree is enabled. After the user marks the body of the service, additional tags, such as the Operation and Method, are enabled. In this way, the user is guided through the process of structuring the Web API description and we limit the potential mistakes that a user could make, thus avoiding the generation of incorrect service description structures. The marking of HTML content with a particular hRESTS tag results in the insertion of a cor- responding class HTML attribute. This formalism complexity is hidden from the user, and instead, he/she only sees the current status of the annotation reflected in the Semantic Description panel. In addition, each inserted tag is highlighted by a custom cascading style sheet (CSS), which visualizes the annotations the user has made. An example of an HTML with identified service properties is given in Listing 1.1. Listing 1.1. Example hRESTS Service Description 1
All operations should be directed at http://happenr.3scale . net/
4where the userkey is the key issues with the signup you made.
7Your username that you received from Happenr in order to query this webservice.
11Your password that you received from Happenr in order to query this webservice.
13The id of the event.
All operations should be directed at http://happenr.3scale . net/
5where the userkey is the key issues with the signup you made.
8Your username that you received from Happenr in order to query this webservice.
13Your password that you received from Happenr in order to query this webservice.
Listing 1.2 shows our example service description annotated with MicroWSMO by using SWEET. Line 2 uses the model relation to indicate that the service searches for events, while line 10 associates the input parameter username with the class Username. The lowering schema for the recipient is also provided in line 11. The annotated HTML of the Web API can be directly transformed into RDF (Listing 1.3), which serves as the basis for discovery and manipulation directly over the semantic properties. Listing 1.3. Example RDF Service Description 1