Guide for Experimenters

5 Reasoning

5.1 Reasoning APIs

Currently, the FIESTA-IoT Reasoning module supports REST APIs for (i) Rule creation, (ii) Rule Registration and (iii) Rule Execution in the following three resources: (i) rule-resource, (ii) register-rule-resource and (iii) execution-resource, as presented in 1st figure. The documentation of the APIs can be found on the FIESTA-IoT portal, under the Help menu. Below, we describe the usage of these APIs.

All requests to the FIESTA-IoT Reasoning API must provide a header with:

  • Content-Type: application/json
  • iPlanetDirectoryPro: SSO Token obtained from the FIESTA IoT authentication API. 



Rule Resource
The Rule Resource API provides several services that can be used by experimenters for creating, editing, updating and validating reasoning rules. The 2nd figure presents the list of services currently supported in the rule-resource API.



Get all rules API
The “getAllReasonings” service provides the function for experimenters to get the list of currently created rules, using parameters such as page, size, and sort. Since the list of created rules can be quite long in real deployments, the experimenter can select the rules according to the following parameters below to limit the number of rules.

URL

/api/reasonings

Method

GET

URL Params

Optional
page=[alphanumeric]

sets the starting page number for the rules to be returned. For example, setting the page to “5”, the reasoning engine will return the rules from number size*5 until size*6-1, depending on the size parameter below.

size=[alphanumeric]

sets the number of rules per page to be returned.

sort=[string]

sets the sorting criteria for the returned result set, i.e. ascending or descending.



Get Rule by ID API
Experimenters can also query the reasoning engine to get a specific rule by providing the rule identification number. This can be done by using the “getReasoning” service of the rule-resource API, using as a parameter only the rule ID, as seen in Table 18. An example of the request for getting a rule by its id is also provided in the table. If the user is authenticated with the FIESTA-IoT platform, the request is as simple as accessing the URL https://platform-dev.fiesta-iot.eu/reasoner-engine/api/reasonings/{rule_id}

URL

/api/reasonings/{id}

Method

GET

URL Params

Required
id=[integer]

The rule id to be returned

 



Create rule
When an experimenter creates a rule, basically he creates a template for the rule, defining the name, description, the quantity kind that the rule should check and an example of sensor from which the rule will check its measurements.
In Table below the description of the service for creating a rule is provided. The service is similar for the semantic and the non-semantic experts, since the latter is mainly used for the Reasoning Tool to be described in D4.8. The experimenters have to define some parameters for:

  • Content: this is the main text describing the rule in a SPARQL query format.
  • Description: this is the description of the rule.
  • Sensor: this is an example URI of a sensor to be used for the rule.
  • Latitude, Longtitude: example location details for the sensor.
  • quantityKind: the modality of the sensor, i.e. temperature, humidity, power, etc.
  • unitOfMeasurement: the measurement unit of the sensor, i.e. RH, degreesCelsius, Watt, etc.
  • reasoning: the json string describing the rule to be created.

An example of the Content parameter for defining a rule for a power sensor “if value > 0.1 then notify_high” is also shown in the table.

URL

/api/reasonings

Method

POST

URL Params

Required:
reasoning=[string]

This is the json string that provides the description of the rule to be created. The json string should be in the following form:

{

  "content": "string",

  "description": "string",

  "id": 0,

  "latitude": 0,

  "longitude": 0,

  "name": "string",

  "quantityKind": "string",

  "sensor": "string",

  "unitOfMeasurement": "string"

}

And content should be in the form of:

 

@prefix iot-lite: <http://purl.oclc.org/NET/UNIS/fiware/iot-lite#> .

@prefix m3-lite: <http://purl.org/iot/vocab/m3-lite#> .

@prefix ssn: <http://purl.oclc.org/NET/ssnx/ssn#> .

@prefix geo:  <http://www.w3.org/2003/01/geo/wgs84_pos#> .

@prefix xsd:    <http://www.w3.org/2001/XMLSchema#> .

@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

@prefix dul: <http://www.loa.istc.cnr.it/ontologies/DUL.owl#> .

@prefix time: <http://www.w3.org/2006/time#> .

@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

@prefix reasoning: <https://fiesta-iot.eu/reasoning#> .(?observation rdf:type ssn:Observation),

(?observation ssn:observedProperty ?observedProperty),

(?observedProperty rdf:type m3-lite:Power),

(?observation ssn:observationResult ?sensorOutput),

(?sensorOutput ssn:hasValue ?obsValue),

(?obsValue dul:hasDataValue ?dataValue),

(?obsValue iot-lite:hasUnit ?unit),

(?unit rdf:type m3-lite:Watt),

greaterThan(?dataValue, “0.1”^^xsd:double) -> (?observation reasoning:announce “notify_high”^^xsd:string).

 



Update Rule API
Experimenters may also need to change some parameters in the rules they have created at some point. For this, the Reasoning Engine provides a service for updating the rules by using the “updateReasoning” service using a PUT command and changing the content of the rule, as seen in Table

URL

/api/reasonings

Method

PUT

URL Params

Required:
reasoning=[string]

This is the json string that provides the updated description of the rule to be created. The json string should be in the following form:

{

  "content": "string",

  "description": "string",

  "id": 0,

  "latitude": 0,

  "longitude": 0,

  "name": "string",

  "quantityKind": "string",

  "sensor": "string",

  "unitOfMeasurement": "string"

}

And content should be in the form of:

 

@prefix iot-lite: <http://purl.oclc.org/NET/UNIS/fiware/iot-lite#> .

@prefix m3-lite: <http://purl.org/iot/vocab/m3-lite#> .

@prefix ssn: <http://purl.oclc.org/NET/ssnx/ssn#> .

@prefix geo:  <http://www.w3.org/2003/01/geo/wgs84_pos#> .

@prefix xsd:    <http://www.w3.org/2001/XMLSchema#> .

@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

@prefix dul: <http://www.loa.istc.cnr.it/ontologies/DUL.owl#> .

@prefix time: <http://www.w3.org/2006/time#> .

@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

@prefix reasoning: <https://fiesta-iot.eu/reasoning#> .(?observation rdf:type ssn:Observation),

(?observation ssn:observedProperty ?observedProperty),

(?observedProperty rdf:type m3-lite:Power),

(?observation ssn:observationResult ?sensorOutput),

(?sensorOutput ssn:hasValue ?obsValue),

(?obsValue dul:hasDataValue ?dataValue),

(?obsValue iot-lite:hasUnit ?unit),

(?unit rdf:type m3-lite:Watt),

greaterThan(?dataValue, “0.1”^^xsd:double) -> (?observation reasoning:announcenotify_high”^^xsd:string.

 



Rule validation
When experimenters want to create or update some rules, to ensure that they are in the correct format before they are executed, they must be validated, using the “validateRule” service as seen in Table below. This service takes two parameters for the rule id and the sensor id and then provides the validation response that can be true or false and a message string describing the result of the validation (i.e. what error occurred).

URL

/api/rule/validate

Method

POST

URL Params

Required:
validateRequest=[string]

This is the json string that provides the information for the rule to be validated. It should be in the following form:

 

{

  "rule": "string",

  "sensorId": "string"

}

 

rule: the id of the rule to be validated

sensorId: the id of the sensor for which the rule will be applied.

 



Register Rule Resource
The Register Rule Resource API provides several services that can be used by experimenters for registering a rule that they have created previously so that they can then execute it on their experiment. By registering a rule, the experimenter defines specifically for which sensor (or set of sensors) the rule will execute. The Register Rule Resource API provides services for retrieving the list of registered rules, for registering a new rule, for updating a rule registration and for getting a specific registered rule. In Figure below the list of services currently supported in the rule-resource API are presented.

List all API in register rule resource



Get all registered rules API
The “getAllRegisterRules” service (presented in Table below) provides the function for experimenters to retrieve the full list of currently registered rules in a similar way like the “getAllRules” service, using parameters such as page, size, and sort. However, here, by accessing this service, the experimenter will only retrieve the list of rules he has registered and not the rules registered by other experimenters. Since the list of registered rules can be quite long in real deployments, the experimenter can select the registered rules according to the following parameters below to limit the number of rules, same as in the “getAllRules” service described in this section. The table also shows an example of the request to get the list of registered rules starting from page 5 with a page size of “10” and sorted descending according to their id.

URL

/api/register-rule

Method

GET

URL Params

Optional:
page=[integer]

sets the starting page number for the registered rules to be returned. For example, setting the page to “5”, the reasoning engine will return the registered rules from number size*5 until size*6-1, depending on the size parameter below.

size=[integer]

sets the number of the registered rules per page to be returned.

sort=[string]

sets the sorting criteria for the returned resultset, i.e. ascending or descending.



Get register rule by id API
Experimenters can also query the reasoning engine to get a specific registered rule by providing the rule registration identification number. This can be done by using the “getRegisterRule” service of the register-rule-resource API, using as a parameter only the registration ID.

URL

/api/register-rule

Method

GET

URL Params

Optional:
page=[integer]

sets the starting page number for the registered rules to be returned. For example, setting the page to “5”, the reasoning engine will return the registered rules from number size*5 until size*6-1, depending on the size parameter below.

size=[integer]

sets the number of the registered rules per page to be returned.

sort=[string]

sets the sorting criteria for the returned resultset, i.e. ascending or descending.



Register rule API
For registering a rule, the experimenters should access the “createRegisterRule” service, where they must define the json string of the rule registration. In the json string, the experimenters must define the rule that they want to register and provide details regarding the sensor they are checking with the rule.

URL

/api/register-rules

Method

POST

URL Params

Required:
registerRule=[string]

This is the json string that provides the description of the rule to be registered. The json string should be in the following form:

{

  "description": "string",

  "latitude": 0,

  "longitude": 0,

  "name": "string",

  "quantityKind": "string",

  "ruleId": 0,

  "sensor": "string",

  "unitOfMeasurement": "string"

}

With the following sub-parameters

  • "ruleID": string

the id of the rule that was previously created and needs to be registered.

  • "Name": string

the name of the rule to be registered.

  • "Description": string

this is the description of the rule registration.

  • "Sensor": string

this is an example URI of a sensor to be used for the rule.

  • "Latitude", "Longitude": example location details for the sensor.
  • "quantityKind": string

the modality of the sensor, i.e. temperature, humidity, power, etc.

  • "unitOfMeasurement": string

the measurement unit of the sensor, i.e. RH, degreesCelsius, Watt, etc.



Update register rule API
Similar as with the rule creation, the Reasoning Engine includes also a service for updating the registered rules, via accessing the “updateRegisterRule” service and defining the new content of the rule registration, i.e. the new sensor.

URL

/api/rgister-rules

Method

PUT

URL Params

Required:
registerRule=[string]

This is the json string that provides the description of the updated registered rule. The json string should be in the following form:

{

  "description": "string",

  "latitude": 0,

  "longitude": 0,

  "name": "string",

  "quantityKind": "string",

  "ruleId": 0,

  "sensor": "string",

  "unitOfMeasurement": "string"

}

With the following sub-parameters

  • "ruleID": string

the id of the rule that was previously created and needs to be registered.

  • "Name": string

the name of the rule to be registered.

  • "Description": string

this is the description of the rule registration.

  • "Sensor": string

this is an example URI of a sensor to be used for the rule.

  • "Latitude", "Longitude": example location details for the sensor.
  • "quantityKind": string

the modality of the sensor, i.e. temperature, humidity, power, etc.

  • "unitOfMeasurement": string

the measurement unit of the sensor, i.e. RH, degreesCelsius, Watt, etc.

 



Execution Resource
After creating and registering a rule, the next step is to execute the rule to see the reasoning results. For this, the Reasoning Engine provides the Execution Resource API with services for retrieving previous executions, creating a new execution and retrieving a specific previous execution, as seen in Figure below.



Get All executions
The “getAllExecutions” service provides the function for experimenters to retrieve the full list of previous executions of their registered rules in a similar way like the “getAllRules” service, using parameters such as page, size, and sort. However, here, by accessing this service, the experimenter will only retrieve the list of their own previous executions and not the executions of other experimenters. Since the list of previous executions can be quite long in real deployments, the experimenter can select the previous executions to retrieve according to the following parameters below in order to limit the number of results, same as in the “getAllRules” service described in this Section.

URL

/api/executions

Method

GET

URL Params

Optional:
page=[integer]

sets the starting page number for the executions to be returned. For example, setting the page to “5”, the reasoning engine will return the previous executions from number size*5 until size*6-1, depending on the size parameter below.

size=[integer]

sets the number of the executions per page to be returned.

sort=[string]

sets the sorting criteria for the returned resultset, i.e. ascending or descending.

example:

page=3

size=30

sort=asc



Get Specific Execution
Experimenters can also query the reasoning engine to get a specific previous execution by providing the execution identification number. This can be done by using the “getExecution” service of the execution-resource API, using as a parameter only the execution ID, as seen in Table below.

URL

 /api/executions/{id}

Method

GET

URL Params

Required:
id=[integer]

The id of the specific execution to be returned

 



Execute Rule
The last action an experimenter must perform to execute a rule is to access the “createExecution” service and create a new execution, by providing a textual description in a json format of the execution, setting the required parameters.
If the experimenter wants to get the reasoning results only on the latest value, then the started/ended should be the same value and should be set to the current date/time. Otherwise, setting the started and ended at different values, the rule will be executed to the list of measurements within these times.

URL

 /api/executions

Method

POST

URL Params

Required:
execution=[string]

This is the json string that provides the description of the new execution to be created. The json string should be in the following form:

 

{

  "started": "2017-10-23T14:04:26.542Z"

  "ended": "2017-10-23T14:04:26.542Z",

  "executeType": 0,

  "registerRuleId": 0,

}

With the following sub-parameters

<![if !supportLists]>-                  <![endif]>"started": datestring

<![if !supportLists]>·                 <![endif]>the starting date of the dataset that will be checked by this rule.

<![if !supportLists]>-                  <![endif]>"ended": datestring

<![if !supportLists]>·                 <![endif]>the ending date of the dataset that will be checked by this rule.

<![if !supportLists]>-                  <![endif]>"executeType": integer

<![if !supportLists]>·                 <![endif]>can be “1” if the experimenter wants to get results only on the latest value or “2” if the experimenter wants the results on a time series.

<![if !supportLists]>-                  <![endif]>"registerRuleId": integer

<![if !supportLists]>·                 <![endif]>The id of the registered rule that will be executed.


The response of an example execution can be seen in Figure below, where the response body includes the results of the execution, containing also the inference results.