lasithac / wot-hive

The WoT Hive an implementation of a WoT Directory described in the W3C WoT Discovery standard

WoT Hive is an implementation of a W3C Web of Things directory . This implementation is compliant with the standard specification but aims at providing enriched features thanks to the usage of other W3C standards related to Semantic Web technologies.

Checkout our wiki for more documentation

Temporally the functionality that introduces the registration information in the Things has been disable (version 0.2.0 and above). Also, at the light of a new update in the Thing Descriptions the semantic validation lacks of a proper shacl shape file and therefore it is strongly recomended to disable this kind of validation.

Docker quick start

Copy this receipt in a docker-compose.yml file

version: '2'
services:
  triplestore:
    image: acimmino/auroral-fuseky:latest
    environment:
     ADMIN_PASSWORD: pw123
    volumes:
    - triplestore:/fuseki
    ports:
      - '3030:3030'
  wothive:
    image: acimmino/wot-hive:latest
    # volumes:
    # - ./configuration.json:/usr/src/wothive/configuration.json
    ports:
      - '9000:9000'
volumes:
  triplestore:

Run the docker command

docker-compose up

[OPTIONAL] Uncomment wothive volume to bind your own configuration file for the wothive. Default file is configured to connect the fuseki service running in the docker-compose network.

[OPTIONAL 2] If you want to change the fuseki service location (Move outside docker for instance), you can change the configuration of the wothive also via API. A POST request must be sent to /configuration/triplestore containing the in the body the following JSON. This

{
    "updateEnpoint": "http://triplestore:3030/sparql",
    "queryEnpoint": "http://triplestore:3030/sparql",
    "queryUsingGET": true
}

Jar quick start

Requires a triple store service publishing a SPARQL endpoint to store the Thing Descriptions

1. Download the WoT Hive service

Download the latest release of WoT Hive into a folder. Notice that the releases have several files that must be downloaded and placed in the same folder:

• log4j.properties allows to customise the logs of the service
• schema.json allows to perform JSON schema validation over the Thing Descriptions
• shape.ttl allows to perform SHACL shapes validation over the Thing Descriptions
• wothive.jar is the jar of the service

Once downloaded all the resources in the same folder the service can be ran using the command

java -jar wothive.jar

When the service is up and running a file called configuration.json will be created in the directory of the jar. The service will run by default in port 9000.

2. Set up the triple store

In order to connect the WoT Hive to a remote triple store a POST request must be sent to /configuration/triplestore containing the in the body the following JSON

{
    "updateEnpoint": "http://localhost:3030/sparql",
    "queryEnpoint": "http://localhost:3030/sparql",
    "queryUsingGET": true
}

Notice that "queryEndpoint"and "updateEndpoint" must have as value the correct endpoints of the triple store for either querying or inserting data. Finally, if the triple store implements the SPARQL protocol through GET requests then leave "queryUsingGET": true, otherwise, for using POSTset it to false "queryUsingGET": false.

WoT Hive API

Endpoint	Method	Headers	Reference	Description
/.well-known/wot	GET	N/A	Introduction Mechanism	Provides the Thing Description of the WoT Hive directory
/.well-known/core	GET	N/A	Introduction Mechanim	Exposes the directory's Thing Description using the CoRE Link Format
/configuration	GET	N/A	Management	Provides a JSON with the all the configurations of the WoT Hive
/configuration	POST	N/A	Management	The body of the request must contain a JSON with all the configurations of the WoT Hive.
/api/status	GET	N/A	N/A	Provides a health check of the service
/api/things{?offset,limit,sort_by,sort_order}	GET	Accept: application/td+jsonor text/turtle	Listing	Provides a listing of the stored Thing Descriptions in JSON-LD framed or Turtle
/api/things	POST	Content-Type: application/td+json	Creation (Anonymous)	Creates an anonymous Thing Description, provided in the body as JSON-LD framed. The generated :id is output in the response headers
/api/things/{:id}	GET	Accept: application/td+jsonor text/turtle	Retrieval	Retrieves the Thing Description with the provided id, in either JSON-LD framed or turtle
/api/things/{:id}	PUT	Content-Type: application/td+jsonor text/turtle	Creation or Update	Creates an Thing Description, provided in the body as JSON-LD framed or turtle
/api/things/{:id}	PATCH	Content-Type: application/merge-patch+json	Partial Update	Partially updates an existing Thing Description, the updates must be provided in JSON-LD framed
/api/things/{:id}	DELETE	N/A	Deletion	Partially updates an existing Thing Description, the updates must be provided in JSON-LD framed
api/search/jsonpath{?query}	GET	N/A	JSON path search	Filters existing Thing Descriptions based on the provided JSON path, the output will be always in JSON-LD framed
api/search/sparql{?query}	GET	Accept : application/sparql-results+json, application/sparql-results+xml, text/csv, or text/tab-separated-values	SPARQL search	Solves a SPARQL query following the standard, results format are in JSON by default if no header is specified. Otherwise available formats are JSON(application/sparql-results+json), XML (application/sparql-results+xml), CSV (text/csv), or TSV (text/tab-separated-values)
api/search/fed-sparql{?query}{?endpoint}	POST	Accept : application/sparql-results+json, application/sparql-results+xml, text/csv, or text/tab-separated-values	SPARQL search	Solves a SPARQL query SELECT or CONSTRUCT over a list of endpoints provided following the standard, results format are in JSON by default if no header is specified. Otherwise available formats are JSON(application/sparql-results+json), XML (application/sparql-results+xml), CSV (text/csv), or TSV (text/tab-separated-values)
api/events{?diff}	GET	N/A	Notifications	Subscribe to all the events of the service (create, update, and delete) using the Server-Sends-Events (SSE) protocol
api/events/create{?diff}	GET	N/A	Notifications	Subscribe to all the create events of the service using the Server-Sends-Events (SSE) protocol
api/events/update{?diff}	GET	N/A	Notifications	Subscribe to all the update events of the service using the Server-Sends-Events (SSE) protocol
api/events/delete{?diff}	GET	N/A	Notifications	Subscribe to all the delete events of the service using the Server-Sends-Events (SSE) protocol

Validation can be configured to ran using the JSON schema of the Thing Descriptions and/or their SHACL shapes.

---

Acknowledgements

This project has been partially funded by:

Project	Grant
	The European project AURORAL from the European Union's Horizont 2020 research and innovation programme under grant agreement Nº101016854.
	The European project COGITO from the European Union's Horizont 2020 research and innovation programme under grant agreement Nº958310.