Keywords

These keywords were added by machine and not by the authors. This process is experimental and the keywords may be updated as the learning algorithm improves.

1 Introduction

1.1 The Web api Simplification Movement

The number of Web apis has increased at a tremendous rate during the past few years. ProgrammableWeb, a major catalog of Web apis and services, consisted of 6,000 entries as of May 2012 [13], twice the amount compared to the year before [12]. More than 4,000 of those entries carry the label “rest”, meaning they are light-weight Web apis, also called http interfaces, as opposed to the more heavy-weight rpc-style Web services, often using soap. While there are certainly different viewpoints to take into account—especially when comparing enterprise soa architects and mash-up developers—Web developers in general welcome this simplification movement on the dynamic side of the Web. It is common practice to intermix Web apis from different sources and, in the sense of emergence, create something new (commonly called mashup applications), where the whole is greater than the sum of its parts. If Web application development today was compared to the world of toys, the lego figures would ride the Playmobil horses and fight with Star Wars collectibles swords. However, a lot of manual plumbing is required to make this work: while Web apis bare the potential to be composed straightforwardly, they lack the semantics to do this in an automated way [26].

In the past, we have introduced the Web api description method restdesc [35], which aims to provide the semantics necessary to enable automated api consumption and composition, in the same way that ontologies provide the semantics to static data. In this paper, we want to look at Web apis from a Semantic Web perspective: investigating how apis differ from data, what they have in common, and how they could work together on the Web. An important piece of the puzzle is to realize that the resource-oriented way of looking at apis is similar to the Linked Data vision on data.

1.2 Linked Data Explains the Static Side, restdesc the Dynamic Side

To clarify what we mean with this statement, we need to take a step back and think about the Web in its most abstract form. What we see are resources, with an unparalleled variety, and an ever increasing number of links between them [10]. Resources and their representations make up the essence of the Web [16], while the Linked Data vision made us all realize again the crucial role that links play therein. Indeed, links have been the catalysts of the success of the human Web, and they continue to prove their strengths on the Semantic Web [8]. The representations of resources—and therefore data—are given meaning by links, corresponding to well-defined rdf predicates.

Given the importance of links, one can wonder why they seem absent on the service-side of the Web, where interactions are mostly driven by static controls such as message templates and uri construction rules. These controls have to be known in advance, unlike Linked Data controls (i.e., the links between resources), which are consumed at runtime. When Fielding redesigned the http specification [15], he had a resource-oriented model in mind where hypermedia drives Web applications: Representational State Transfer (rest, [16]). He later clarified that the hypermedia constraint imposed by rest demands that representations of a resource should contain controls that guide hypermedia consumers to possible next steps or resources [14]. Consequently, modeling Web apis the rest way leads to the same resources-and-links paradigm that is at the core of the human Web, which has html links and forms, and the Semantic Web, which has rdf links between resources.

In all fairness, rest apis—as defined by Fielding—are scarce. While many apis carry the “rest” label, few actually obey the hypermedia constraint, and, even worse, some of them do not correctly adhere to the defined http semantics [26]. Hypermedia-driven apis are vastly outnumbered by plain http and rpc interfaces. However, this can be compared to the larger presence of unstructured and unlinked data on the Web compared to Linked Data. Therefore, the scarceness doesn’t change the status of resource- and link-orientedness as well-suited model for automated agents to perform static and dynamic interactions.

Currently, the main obstacle for automated agents that want to consume Web apis is that they cannot predict what effect a state-changing operation will have. Linked Data gives the answer for information-retrieving operations, known as dereferencing. Performing a GET operation on a resource’s uri will provide the agent with information about that resource. But what happens when the agent performs a POST operation on the same resource? Reference [35] Since Fielding suggests the controls (e.g., links and forms) should point to possible next steps or resources, it is obvious how the state change happens. However, what this state change will bring might be obvious to humans, but is still unknown to machines. Therefore, in this paper, we zoom in on how the description format restdesc explains to agents what will happen if state-changing operations are performed on a resource, complementary to the Linked Data principles that explain the same for static operations.

This complementary nature is illustrated in Fig. 1, which positions Linked Data and restdesc. The example shows a book store that offers several books, each of which can have several reviews. The resources might be available on the Web for human visitors as html representations with (possibly typed) hyperlinks in between. To make the store machine-accessible, the server might additionally serve rdf representations, in which the relations are rdf predicates, which eventually can lead to Linked Data. However, the Linked Data principles only explain how to browse books and reviews, whereas the html representations provide the controls to add reviews. restdesc bridges this gap by explaining the functionality of this Web api, in a representation-independent way.

Fig. 1.
figure 1

restdesc complements Linked Data by explaining a hyperlink’s dynamic functionality in machine-readable form. For instance, we can express with restdesc what happens when agents use POST on a linked resource instead of GET.

Full size image

This paper starts with a description of related work in Sect. 2, then highlights the differences and similarities of Linked Data and hypermedia apis in Sect. 3, zooming in on the gaps that need to be bridged. Section 4 continues with an illustration of the role restdesc can play herein by formally expressing the relationship between resources in a hypermedia api. Finally, Sect. 5 looks back on the discussed topics and ends by indicating the importance of hypermedia-driven apis on the Web for autonomous agents.

2 Related Work

Description of Web services or apis for automated use has been on the Web since before the advent of the Semantic Web (notably wsdl [11]), and played an important part during the beginning of the Semantic Web’s inception. Several of the first initiatives are well-known: owl-s  [29], which evolved from daml-s [3], and the conceptually different wsmo [24, 32]. These formats target what are called “Big” Web services [31], which function in a message-passing or Remote Procedure Call (rpc) paradigm. While these models use Semantic Web elements such as ontologies, they predate the Linked Data vision and the recent revaluation of rest apis. Neither owl-s nor wsmo have stood the test of time, as extensive Web searches did not reveal substantial real-world usage. We therefore focus on more recent research projects that have design goals similar to restdesc, e.g., a focus on functionality and/or hypermedia apis.

Several methods aim to enhance existing technologies to deliver annotations of Web apis. html for restful Services (hrests, [21]) is a microformat to annotate html descriptions of Web apis in a machine-processable way. sa-rest [18] provides an extension of hrests that describes other facets such as data formats and programming language bindings. Microwsmo [22, 25], an extension to sawsdl that enables the annotation of restful services, supports the discovery, composition, and invocation of Web apis. The Semantic Web sErvices Editing Tool (sweet, [27]) is an editor that supports the creation of mashups through semantic annotations with Microwsmo and other technologies. A shared api description model, providing common grounds for enhancing apis with semantic annotations to overcome the current heterogeneity, has been proposed in the context of the soa4all project [28].

The Resource Linking Language (rell, [1]) features media types, resource types, and link types as first class citizens for descriptions. It offers a metamodel and an associated xml Schema to capture these aspects formally. The restler crawler [1] finds restful services based on rell descriptions. The authors also propose a method for rell api composition [2] using Petri nets to describe the machine-client navigation.

Linked Open Services (los, [23]) have an http api approach, in which sparql graph patterns identify the offered functionality. Part of the project’s scope concerns the lifting and lowering of existing services, since many of them do not expose their data in a semantic format yet. A difference with restdesc is that los apis are not committed to the hypermedia constraint, whereas the hypermedia-driven consumption of apis is a central concept in restdesc.

Linked Data Services (lids, [33]) have a similar notion of input and output graphs. They use the input data to construct a resource’s uri, as opposed to los, which sends input data in the request body. The result is an api whose interactions are thus in a sense solely form-based—the form structure being defined by the unbound variables in the input graph pattern. In addition to forms (not discussed in this paper), restdesc also aims to support the link part of the hypermedia control set.

3 A Joint Future for Linked Data and Hypermedia APIS

We start this section with an essential definition to avoid misunderstandings on the thin ice of rest, restlike, and unrestful apis:

  • Hypermedia Web APIS are interfaces to retrieve and manipulate resources according to the http method semantics, serving representations of these resources along with the controls to advance through the interface [14].Footnote 1

Striking parallels between Linked Data and hypermedia apis exist—and this is not a coincidence, since both are closely tied to the original visions and architecture of the Web. One of the common elements are resources: concepts in Linked Data are identified by one or multiple uris, which, when requested through http  GET, lead to information about that concept. Hypermedia apis are similarly structured as concepts or resources, with the constraints that every uri should identify a resource and that the http methods should be used conform to the http specification [15]. The semantics of the GET method have therein been defined as “obtaining the information identified by the uri”, which, unsurprisingly, matches the Linked Data purpose [19].

The other common element are links: as the name implies, they play a vital role in Linked Data, and they are at the heart of the Semantic Web. Links give a concept’s data meaning beyond its own context. More concretely, if an agent does not understand what a data property means, it can look up that property because its link is an http uri. The same applies to hypermedia apis: the controls, telling us how other resources relate to the current resource, can be links. Details on the nature of the relation are conveyed by link types, which can have the same uris as Linked Data properties [30].

In essence, one could see the whole Linking Open Data Cloud [9] as a large, distributed hypermedia application. This is in fact how its usage is encouraged: an agent starts from one resource and can make its way through the whole cloud, just by “following its nose”, thanks to the links. However, it only provides a subset of the possibilities of what we expect from a hypermedia api: merely retrieval operations are supported. Yet, the role of links here remains important: browsing billions of triples in billions of resources would otherwise prove difficult.

An interesting aspect of rest is that it does not matter whether the resources and triples already exist. They can either be part of documents, or be the result of a service invocation—but the agent does not have to know and does not have to care. For example, a huge dataset of natural numbers has been made available as Linked Data [38], yet the information of each number is not static, but instead generated dynamically when an agent dereferences its uri. This dataset is thus what we would traditionally consider a “service”, but thanks to the rest principles, it manifests itself as just another set of linked resources.

Nevertheless, we often associate the concept of services additionally with action-driven behavior, for example, allowing us to post a comment or order tickets. In a rest architectural model, these actions are captured by the modification or creation of resources, linked to existing resources. While these and similar actions are very common on the human Web and on the Web of services, the Semantic Web still struggles with state-changing operations [7]. Several mechanisms are there (e.g., sparql UPDATE [17]), but issues such as authorization and security still impede wide adoption. Consequently, the Linked Data vision must in the meantime assume that the publisher and consumer sides are distinct, i.e., that consumers of Linked Data will not need to perform write operations. This simplifying assumption has its benefits—just look at the overwhelming amount of data—but will not be sufficient for the vision of autonomous agents that require actions in the real world. Indeed, as the comment and ticket examples indicate, many interactions we perform on a daily basis involve write actions. Therefore, in the next section, we will look at the requirements of agents for browsing full hypermedia apis, which offer both information-retrieving and state-changing operations.

4 restdesc Describes Hypermedia Links

4.1 Example Scenario

As an example, let us consider the situation of Fig. 1. Starting from the book store’s main uri, an agent discovers resources in a fully hypermedia-driven way. Its steps might be the following:

  1. 1.

    GET a representation of the index resource at /.

  2. 2.

    Find a hasBook link in this representation titled “The Catcher in the Rye”.

  3. 3.

    GET a representation of this linked resource at /books/443.

  4. 4.

    Find a hasReview link in this representation.

  5. 5.

    GET a representation of this linked resource at /books/443/reviews/7.

This way of working is hypermedia-driven, because the agent only follows the representation-supplied controls (e.g., links) to go from one step to the next.

4.2 Understanding the GET Operations

As an introduction to restdesc, we will know discuss the restdesc description that is associated with the action of retrieving a book’s representation. restdesc descriptions are expressed in Notation3 (n3, [5]), a small superset of rdf put forward by Tim Berners-Lee. n3 adds support for quantification, necessary to create statements concerning all resources instead of only specific ones. Without this explicit support, the quantifications should have to be expressed indirectly. One other possibility to express this is to wrap sparql expressions inside string literals, which is the method used by lids [33]. The quantification constructs in n3 enable to integrate the semantics directly, whereas for instance sparql expressions have to be interpreted separately.

figure a

Listing 1 displays a description of the GET operation on the hasBook link type and serves as an illustration of several common aspects of restdesc descriptions. Every description is a logic implication. The logical foundations of n3 (n3logic, [6]) define an operational semantics, i.e., restdesc descriptions are n3 rules that can be instantiated and executed by a reasoner. As indicated in Listing 1, it is convenient to examine the description in three parts:

figure b

IF you obtain a book’s uri from a hasBook hyperlink

figure c

THEN you can make a POST request to that uri

figure d

to retrieve a representation of this book.

Below, we discuss some important aspects of this description.

Firstly, the explicit quantification makes agent understand that the book in the antecedent and the conclusion are the same. The ?book variable can be instantiated with a concrete instance. For example, if an agent finds a hasBook link from the store / to the book /books/443/, it can instantiate the description of Listing 1 into the rdf fragment in Listing 2. This fragment details the instructions an agent needs to execute. Since this request in these instructions has not been executed, the resulting values are not known yet. However, the reasoner has instantiated them with blank nodes (title1, author1, and review1). After a successful execution of the request, these blank nodes can be substituted by the actual data received from the server.

Secondly, it might seem strange at first sight that the request 

figure e

is part of the consequent, and not of the antecedent. After all, it is the existence of the link 

figure f

and the execution of the request 

figure g

that lead to obtaining information about the book 

figure h

. However, restdesc adopts a different view here. In fact, it is because of the existence of the link 

figure i

, that a request exists 

figure j

which will lead to the information 

figure k

. The word exists is important here: the description indeed states that a request exists that will deliver the information, not that all requests with the given parameters will lead there. In other words: the request is existentially quantified, not universally. This notion is important, because it models the world more accurately. For example, a given request could fail because of connection issues or might require additional authentication.

figure l

Thirdly, restdesc does not specify what representations should look like. This is a central part of the restphilosophy. While restdesc describes the relations between resources and the result of actions performed on them, the selection of the right representation should happen at runtime by making use of the content negotiation mechanism of the http protocol. For example, Listing 1 states that the retrieved resource will have a title and an author. The description does, however, not imply that this information will be supplied in rdf or any other format. While it seems logical that an agent would ask for an rdf representation (since the agent uses Semantic Web technologies internally), this is by no means a requirement. The actual representation could be in xml, json, html, or any other format. This opens possibilities to work with non-textual data, such as images and video [36]. However, the major benefit of rdf representations is that their contents are self-describing and can therefore be automatically interpreted by machines.

The final and most crucial remark is that the necessity of the description in Listing 1 can be questioned. After all, why would we want to describe a GET request? It seems unnecessary, because of the following two reasons: first, the Linked Data principles already tell us what happens with GET request—receiving a representation of the resource with the corresponding uri (which is called “dereferencing”). Second, even if these principles did not apply, an agent could safely execute the request, since the http specification indicates GET should not change application state [15]. We fully agree here: restdesc is designed to describe state-changing operations whose result is resource-dependent, the primary verb being POST. Therefore, the next subsection illustrates a POST request, which fully illustrates restdesc ’s capabilities. restdesc can however be used for GET, which is interesting (a) for situations where ontological constructs are insufficient to describe a complex resource relationship and (b) to convey an expectation of what properties a representation will contain (e.g., hasTitle, hasAuthor, ...).

figure m

4.3 Understanding POST Requests

The situation is completely different for POST requests because, unlike with GET and other safe requests, the agent cannot carelessly issue a POST request in one of the steps, since (a) it cannot predict what the result will be and (b) testing what the result is can have unwanted consequences, as POST is unsafe [15]. Furthermore, it cannot determine what body it should send along with the POST request. Although some representation formats provide forms (e.g., html and Atom), others lack form functionality (e.g., rdf, although proposals exist [4]), but in either case, it is unclear how the result relates to the submitted data.

Let us therefore examine the description in Listing 3, which can similarly be interpreted in three parts:

figure n

if you obtain a book’s uri from a hasBook hyperlink

figure o

then you can make a POST request to that uri

figure p

to add a review with the supplied parameters to this book.

This enables agents to understand what data they can send along with a POST request and how this data will influence the outcome of the request.

Note how, in this example, the precondition is more restricting: the agent needs to have access to a review before the request can be executed. Also, this review is necessary to construct the request: it should be placed inside the http request’s POST body. Again, the exact representation of this body is not detailed, because agents and servers should be able to agree on the best representation at runtime. We do, however, get a suggestion of properties that should be present in the representation: an author, a rating, and a review text.

Now that the agent understands each of the steps, it is able to chain them together and actually execute each of the requests in the process.

4.4 Executing the Requests

Concretely, if the agent has been given the contents of a review (author, rating, content), it can follow these hypermedia-driven steps:

  1. 1.

    GET the restdesc description of hasBook.Footnote 2

  2. 2.

    GET a representation of the index resource at /.

  3. 3.

    Find a hasBook link in this representation titled “The Catcher in the Rye”.

  4. 4.

    Instantiate the description with the review and found link.

  5. 5.

    POST the review, as instructed by the description, at /books/443.

Note again how only hypermedia controls are used to get from one step to the next. The added value of restdesc here is to explain the agent in advance what effect the POST request will have, so it can decide whether to execute this request. In real-world applications, restdesc descriptions can be used for goal-driven api compositions [37]. For instance, the user can supply the review parameters as input, and ask that it is submitted to a certain book.

5 Conclusion

The Linked Data vision strives to connect data on the Web, making it available in a machine-processable format. Hypermedia apis similarly strive for connectedness of resources, but also consider the write side of interactions. Their goals are similar, and so are their tools: both make automated consumption of the Web available using the core principles of the http architecture, featuring resources, representations, and links. However, dealing with state-changing operations requires automated agents to have expectations of what consequences their actions will have.

restdesc shows how existing Semantic Web technologies can be combined to explain the functionality of a Web api to those agents. It enables us to apply the Linked Data vision to hypermedia apis by describing the meaning of links for state-changing operations. In that sense, it is a plea for more hypermedia apis on the Web, as they beautifully incorporate the controls that future autonomous agents will need to browse the Web. Therefore, we believe it is time to transition today’s services towards hypermedia apis by adding the missing links.