Autonomous services discovery, composition and execution is an important problem in the Machine-to-Machine field. Achieving this objective requires addressing several issues: a) how to describe in a machine-understandable format which operations and functionalities an object is able to perform; b) how to represent the interfaces in unambiguous way and allow two or more machines to understand the data exchanged with each other; c) how to make a machine able to aggregate services in order to execute a specific task. Narrowing the domain just to REST APIs, we propose to semantically describe APIs (exposed by objects or web servers) using RESTdesc descriptions and to use JSON-LD as data exchange format. In order to illustrate the straightforward services composition and invocation process, we have implemented a smart client able to generate and execute plans (sequences of HTTP requests) that satisfy the set of operations which should be done for ensuring ideal environmental conditions to plants in a garden.
Machine-to-Machine (M2M) interactions, the ability of devices to exchange data in
order to execute a task not explicitly required by a human being, has become a promising
domain for the next-generation communications, and is undergoing a rapid spread and
development. M2M communications are expected to grow exponentially in the near
future, aided by the large deployment of sensors, actuators, RFID/NFC tags. Ericsson’s
Media Vision 2020 research has predicted that by 2020 there will be 50 billion
connected devices [
The first issue is to describe what functionalities a device provides using a machineinterpretable format. In other words, each machine has to be able to o er semantic descriptions of its services. As smart objects are commonly equipped with actuators that determine their states, semantic descriptions should also contain information about the behavior an object applies when its services are invoked. The service composition problem takes as input a set of service descriptions and a goal, and consists in generating a plan/workflow represented by a ordered sequence of services that have to be invoked in order to satisfy the goal. Finally, in order for two (or more) systems to communicate successfully, there has to be a well-defined and universal semantics on the exchanged data, and a way for knowing at runtime the used interfaces.
In this paper we present a method to enable machines to automatically compose
and use services through standard semantic technologies. Despite the proliferation of
protocols with which two or more machines could communicate (e.g. Bluetooth Low
Energy, Zigbee, Xbee), we are witnessing the emergence of microcontrollers directly
connected to the Internet and which can host small web servers and then provide
REST APIs. According to the Web of Things (WoT), the physical world becomes thus
“integrable” with traditionally Web services. Therefore, in our work, a machine is, first of
all, a Web server that exposes a hypermedia API, which demands that a server supplied
the possible next steps alongside each resource. That way, an agent does not need to
know in advance how to use an API; instead, it can just follow the links at runtime
through these supplied hypermedia controls [
To allow cooperation between machines, we propose to describe the functionalities of
APIs through RESTdesc [
In our early work [
The present paper is structured as follows. The next Section contains a brief description on the state of art about already existing methods for describing and composing REST APIs. In Section 3, we explain the technologies we have adopted and the proposed approach. As proof of concept about the feasibility and flexibility of the method introduced in this work, a use case has been implemented on the field of smart gardens and is presented in Section 4. Section 5 contains the evaluation of our approach and Section 6 concludes the paper and provides an overview of future work. 2
In this section, we discuss some related works about syntactic and semantic descriptions of REST APIs and present some existing approaches in services composition.
REST-based services are still almost exclusively described by human-readable
documentation, due to a lack of universal formalism. SA-REST [
Other types of approaches to describe the functionality of Web APIs are based on the
definition of specific ontologies. This is the case with the Hydra Core Vocabulary [
The composition of Web APIs is still a task that is mainly done manually by users. Many
applications allow to connect logical blocks which represent Web services or physical
devices. Two of the best-known of such types of tools are IFTTT [
In the state of art we have found many architectures supporting creation,
management and execution of service mashups directly on the Cloud. SenseStream [
In this context, activities of standardization led by ETSI TC M2M [
In order to create an ecosystem of interoperable devices able to communicate each other and satisfy goals involved in an algorithm in a fully automated way, the first step is to find the technologies able to answer the following questions: a) how can a server describe the semantic meaning of its APIs and its states in machine-understandable format?; b) @prefix vocab: <http://example.org/vocab#>. @prefix http: <http://www.w3.org/2011/http#>. @prefix st: <http://www.mystates.org/states#>. @prefix log: <http://www.w3.org/2000/10/swap/log#>. @prefix bonsai: <http://lpis.csd.auth.gr/ontologies/bonsai/BOnSAI.owl#>. { ?actuator a vocab:IrrigationPump. ?state a st:State;
log:includes { ?actuator vocab:hasSwitchingState ?oldValue. }. ?newValue a bonsai:SwitchAction;
vocab:hasValue ?val. _:request http:methodName "PUT"; http:requestURI (?actuator ?val); http:resp [http:body ?actuator]. [ a st:StateTransition; st:typeOperation "replacement"; st:oldComponent { ?actuator vocab:hasSwitchingState ?oldValue. }; st:newComponent { ?actuator vocab:hasSwitchingState ?newValue. }; st:originalState ?state ]. Listing 1 This RESTdesc description represents a service to transit from the current on/o state to another for an irrigation pump how can a client invoke an function of an API without prior knowledge about the service name and what the server expects and returns?. The answers to these questions will be described in the next subsections. 3.1
Candidate technologies, in order to describe the functionalities of the Web APIs, must take into account that real-world objects have properties that represent their physical characteristics and capabilities. The value for each property at a given time determines the object’s state. For example, the defining property for a multicolor lamp is its color. Its capability is to change color when the value of this property is modified. Therefore, descriptions need to express the concepts of properties and interstate transitions.
We have selected RESTdesc [
One of the main obstacles for more flexible clients are heterogeneous data format and services interface issues. Semantic technologies can mitigate the problem of interoperability and expressiveness in the exchanged data, but formats like RDF/XML, Turtle or N3 are widely disliked to APIs’ developers and have not been optimized for Web APIs.
The power of JSON-LD has been to combine technologies from both the world of Web APIs and the Semantic Web in order to produce a data interchange format human/machine-understandable. Each JSON-LD message is a self-descriptive message, both data and their semantic meaning are transmitted at the same time in the same message. An important its feature is that each JSON-LD message can be converted in RDF format and viceversa. Furthermore, since JSON-LD is 100% compatible with traditional JSON, it is not needed to understand RDF to work with it.
Listing 2 JSON-LD response sent by a irrigation pump when it is switched on
JSON-LD requests and responses optimally fit with data represented in RESTdesc descriptions allowing a simple and straightforward execution of chains of RESTful APIs. The Listing 2 is the response received from a client when it does the request to switch on the irrigation pump identified by http://localhost:3300/actuators/1 URL. This JSON-LD message shows that the resource is a vocab:IrrigationPump and has a SwitchingState whose value is the boolean data “true” (the meaning is that the actuator is switched on).
The conversion of this JSON-LD in to RDF will generate the Listing 3. Comparing the resulted RDF with the RESTdesc description of the Listing 1, it is possible to see the high degree of correlation and correspondence in them. In fact, RESTdesc description not only suggests that the response to the PUT HTTP request (line 17) will be an actuator resource but also contains already the information decoded in RDF (the type of resource Listing 3 JSON-LD of Listing 2 converted in to RDF (without prefixes for brevity) <http://localhost:3300/actuators/1> a vocab:IrrigationPump. <http://localhost:3300/actuators/1> vocab:hasSwitchingState _:b0.
_:b0 a bonsai:SwitchAction; vocab:hasValue "1"^^<https://schema.org/Boolean>. and properties). In other words, if we interpret a JSON-LD as triples, we can see it actually realizes the N3 description we have. 4
In order to illustrate the theoretical services composition and invocation process, we have implemented a use case on the field of smart gardens. 4.1
The objective of our use case is to create a smart garden system that autonomously monitors environmental conditions and decides how and when to act in order to ensure plants thrive. Real-time data about the current environment conditions can be got through sensors (light, temperature and soil moisture) directly located in the garden and associated to each plant or using the information produced by weather stations. In order to reach the ideal environment conditions, each plant is associated to one or more actuators (irrigation pumps, lamps, heaters and automated windows for greenhouses) whose status changes during the execution of the decision-algorithm. The entities involved in our use case are: – one Internet-connected microcontroller, i.e. a embedded board, that runs as server and implements the Garden API3; sensors and actuators are directly connected to the board (that could be an Arduino Yun, STM32 Nucleo, Intel Edison, and so on). Moreover, the board stores plants’ information like type, species and ideal light, temperature and soil moisture values during the di erent parts of day (morning, afternoon, night). Finally, we assume that the embedded board has a GPS module in order to know its geographical coordinates. – Weather web server which implements the Weather Forecast API4; it returns the current and forecast weather conditions for the required location (expressed in geographical coordinates or city name). – Smart client which is implemented as a software module5; it has the task to execute a decision-algorithm in order to ensure the ideal environment conditions for each plant. No pre-knowledge about what the APIs do and how invoking their services is needed, because the smart client is able to understand the APIs’ functionalities and, generate and execute plans that meet the goals whose the algorithm is composed. The client can execute four types of algorithms progressively more complete: 3 Available: https://github.com/dventura3/irrigation-api 4 Available: https://github.com/dventura3/weather-forecast-api 5 Available: https://github.com/dventura3/plants-planning-agent 1. In the first algorithm, the smart client uses only the real-time information given by sensors to determine what status the actuators should have. 2. In case that a sensor is temporarily out of service (e.g. it is not connected to the Network) or a plant has not been associated to a certain type of sensor, the use of the current weather conditions, given by a weather API, can overcome the lack of sensors’ data. Therefore, the second algorithm combines the current weather conditions and sensors’ values to determine the actuators’ states. 3. Using the forecast weather condition is a good practice to decide when to switch on/o the irrigation system in a garden or how to increase or decrease temperature/light in a greenhouse. For example, if a plant needs to be watered but it is expected that soon it will rain, it is possible to avoid turning on the irrigation pump and simply wait. Therefore, in this third algorithm, the client generates plans to know the weather forecast for the next three hours before to set the actuators’ states. 4. It is the same of the third algorithm, except for the fact that the smart client uses the forecast weather conditions for a longer time, the next three days. 4.2
Since the generation and the execution of APIs compositions is done by the smart client, we describe its architecture, highlighting its main features in the next subsections.
The client has a list containing IP and Host for each server (board or Web service)
and, during the initialization phase, uses it to get all the RESTdesc descriptions invoking
HTTP OPTIONS requests. After that, the Algorithms Manager can execute one of four
algorithms every 5 minutes. Whatever algorithm is chosen, it consists in a sequence
of instructions that involve remote services. Therefore, the Proxy is the block that has
Listing 4 Part of output generated by Reasoner. For the sake of brevity, we report only
the plan that will be really executed in order to get the sensors values for one board
to select/generate the goal associated to each specific service required by Algorithms
Manager and initialize the Planner. The latter executes the Reasoner which produces
all the possible plans that achieve the goal. These plans are transformed in a
machinereadable format by the Parser so that the Planner can determine that one to execute.
The plan execution consists in to invoke the services in order and use the JSON-LD
data of X response as input of X+1 request until the end of the plan. When the whole
plan is terminated, the final result is processed by the Proxy and communicated to the
Algorithms Manager, so that the execution of the algorithm can progress.
All the four algoritmhs include the following goal: “Get sensors values associated with
each plant monitored by each embedded board known by the client”. In order to solve
this statement, the first operation to do is to find all the possible plans that fulfil the goal.
This is the Reasoner’s task. As defined in a previous work [
I ) S1 ) S2 ) ::: ) Sx ) G
Of course, the way to meet the goal may not be unique, so many chains of dependency
(i.e. plans) can be found. As the RESTdesc descriptions are N3 descriptions, any N3
reasoner can generate these plans. We have used EYE [
I ) lemma27 ) lemma28 ) lemma29 ) G In order to select one plan and execute the composition, the plans must be understood by client. The N3 format presented in the Listing 4 is not easy to use for a machine/software. Therefore, the Parser converts the output generated by Reasoner in JSON object properly formatted. 4.4
The Planner has the task to select and manage the plan execution. Using the example in the previous subsection, the Planner should decide one of the three plans shown in the Figure 2. As previously said, only the first column of URIs, used to pass from Initial state to the next state, are known to the Parser, while we reveal the URIs of inner states just for descriptive purpose. Lacking a mechanism of cache server (we have not implemented yet) and taking into account the third plan does not have any reference to the associated plant(s), we have decided to always select the longest plan, i.e. the first. Although more complex, it is more reliable.
In order to execute the plan, the Planner needs to know all details of what each HTTP request to those APIs should like. Fortunately, this information is contained in RESTdesc descriptions and is kept by Parser. The execution starts from the first lemma and the result is used to find the URI(s) in order to execute the next lemma. For this scope, a bottom-up algorithm was implemented. To understand how it works, look at the Listing 4. Suppose we have to find the requestURI of lemma28. The blank node associated to the requestURI is _sk5_2. The first part, i.e. “sk5”, identifies the blank node in the lemma27 from which extracting the URI that we are searching. This blank node is _sk5_1, a Plant. We can’t stop here, but we have to go up until the URI of lemma27 because we have to know if _sk5_1 is only one or are many plants. In other words, we have to understand if we are searching just one or many URIs, because one (or many) of visited nodes could be a collection. This is exactly what happens in our example. Infact _sk5_1 is member (the semantic property is hydra:member) of the collection http://127.0.0.1:3300/plants. As demostrate in the Section 3, RESTdesc descriptions are strictly correlated with the JSON-LD responses returned by server. In fact, the http://127.0.0.1:3300/plants call returns a JSON-LD with a vocab:PlantsCollection whose members (the property is hydra:member) are the URIs (of type vocab:Plant) we are searching. We use them to advance in the execution of the plan. Similar considerations can be done to find the requestURI of lemma29 and complete the plan. 5
In order to evaluate our approach, we have measured the average time spent by the Smart Client’s blocks to generate and execute each of the four algorithms. The simulations have been conducted using a Raspberry Pi Model B+ with processor Broadcom SoC at 700 MHz and 512 MB of RAM. The results are shown in the Table 5. The measurements have been split in two operations: a) reasoning and parsing (to know the time used to produce all the possible plans that achieve the correspondent goal); b) selection and execution (involving the only plan that is really executed). The simulations have been conducted with two di erent configurations: a) one plant, one sensor and one actuator; b) three plants, each of them has associated the same three sensors and actuators.
The number of plants, sensors or actuators for each board does not influence the
Reasoner and Parser’s tasks. This happens because their work is strictly correlated with
the number of APIs known to system and not with the data received when the APIs are
invoked. In other words if the number of APIs involved in to achieve a goal increases, also
the time spent to generate all the possible plans will increase linearly, as demonstrated in
our previous work [
An other important aspect is about the number of requests necessary to accomplish a plan. Note that selecting the longer plan has often as consequence to replicate HTTP requests already executed. For example, all the three plans used to get information about the ideal conditions of the plants or sensor values or actuators states associated with each plant, need to invoke: 1) /plants and then 2) /plants/idPlant. These two requests are done three times for the three di erent plans. A more accurate implementation could take account of historical requests. The alternative, as already suggested, is to use a cache server mechanism and choose not to perform the longer plan. Moreover, in other use cases, information as energy consumption could be used to choose the best plan. 6
In this paper, we presented an approach to enable machines to compose and execute REST Web APIs in a fully autonomous way. Our proposed is built on using RESTdesc as method to describe the functionalities of services exposed by physical objects or web servers, and JSON-LD as data exchange format. A machine or software agent can generate plans involving REST Web APIs in order to achieve a goal simply using standard Semantic Web reasoners. Implementing a smart client able to run algorithms that ensure ideal environmental conditions to the plants in a garden, we have demonstrated that these two technologies are deeply correlated and permit a straightforward plans execution. Furthermore, the approach we followed has threefold benefits. First, it achieves an improved decoupling between client and server. If the server’s API is updated and the name or the order of parameters for invoking the API change, the code on the client side is not a ected by these changes. Second, if a server becomes (temporarily) unavailable, the client may perform an alternative plan for getting to accomplish the goals. Third, the same algorithm could be run di erently at di erent times by implementing policies to choose the more convenient plan depending on the context or the purpose of the use case. As future work, we would like to generalize the implementation associated with the use case, so as to be reusable in other Machine-to-Machine scenarios.