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/helio-cloud-rdf4jstore:latest
    volumes:
    - ./triplestore:/usr/src/helio-cloud-rdf4jstore/rdf4j
    ports:
      - '4567:4567'
  wothive:
    image: acimmino/wot-hive:latest
    # volumes:
    # - ./wothive/configuration.json:/usr/src/wothive/configuration.json
    ports:
      - '9000:9000'

[OPTIONAL] Uncomment wothive volume to have access to the configuration file in your host machine

Run the docker command

docker-compose up

IMPORTANT: In order to connect the WoT Hive to the triplestore docker service a POST request must be sent to /configuration/triplestore containing the in the body the following JSON

{
    "updateEnpoint": "http://triplestore:4567/sparql",
    "queryEnpoint": "http://triplestore:4567/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

```bash
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:4567/sparql",
    "queryEnpoint": "http://localhost:4567/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-thing-description	GET	N/A	Introduction Mechanim	Provides the Thing Description of the WoT Hive directory
/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/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/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 the European project AURORAL from the European Union's Horizont 2020 research and innovation programme under grant agreement Nº101016854.