Search

The WoT Hive directory implements two search mechanisms, JSONPath and SPARQL.

JSONPath search

In order to filter the stored Thing Descriptions the WoT Hive publishes the endpoint /api/search/jsonpath to which a client can submit a GET request with a valid JSONPath query. For instance, if a client aims at finding all the Thing Descriptions that have a title, the following request must be sent:

GET /api/search/jsonpath?query=$.title

Notice that the output of a JSONPath query could be just a field or an array of Thing Descriptions fulfilling the query.

SPARQL search

The WoT Hive directory implements a SPARQL endpoint according to the W3C standard; in particular the query via GET, query via POST urlencoded, and query via POST directly are implemented. Regaring SPARQL federation the directory relies on the triplestore SPARQL service, therefore, if the underlying triplestore supports federation the directory allow this kind of queries.

The SPARQL queries must be sent to the endpoint /api/search/sparql, in addition using the following headers must be sent for obtaining the results:

Method	Content-Type
GET	None
POST urlencoded	application/x-www-form-urlencoded
POST directly	application/sparql-query

Content-negotiation

The SPARQL endpoint provides the results of the queries in different formats depending on the kind of SPARQL query. The following table summarises the headers that could be used for obtaining the query results in different formats depending on the SPARQL types:

SPARQL query type	Output format	Accept header
SELECT or ASK	JSON (default without headers)	application/sparql-results+json
SELECT or ASK	XML	application/sparql-results+xml
SELECT or ASK	CSV	text/csv
SELECT or ASK	TSV	text/tab-separated-values
DESCRIBE or CONSTRUCT	TURTLE (default without headers)	application/x-turtle or text/turtle
DESCRIBE or CONSTRUCT	N-TRIPLES	application/n-triples
DESCRIBE or CONSTRUCT	JSON-LD Thing Description framed	application/td+json

An example

For this example let's use the following SPARQL query that retrieves all the titles of the Thing Descriptions stored:

PREFIX td: <https://www.w3.org/2019/wot/td#> 
PREFIX dc: <http://purl.org/dc/terms/>
SELECT ?title {
	?s dc:title ?title .
}

SPARQL via GET

In order to send the SPARQL query a client must follow these steps:

1. Encode the query as a URL, for the previous query example:

PREFIX%20td%3A%20%3Chttps%3A%2F%2Fwww.w3.org%2F2019%2Fwot%2Ftd%23%3E%20%0APREFIX%20dc%3A%20%3Chttp%3A%2F%2Fpurl.org%2Fdc%2Fterms%2F%3E%0ASELECT%20%3Ftitle%20%7B%0A%09%3Fs%20dc%3Atitle%20%3Ftitle%20.%0A%7D

2. Send a GET request to the SPARQL endpoint codifying the query as a parameter:

GET /api/search/sparql?query=PREFIX%20td%3A%20%3Chttps%3A%2F%2Fwww.w3.org%2F2019%2Fwot%2Ftd%23%3E%20%0APREFIX%20dc%3A%20%3Chttp%3A%2F%2Fpurl.org%2Fdc%2Fterms%2F%3E%0ASELECT%20%3Ftitle%20%7B%0A%09%3Fs%20dc%3Atitle%20%3Ftitle%20.%0A%7D

As a result, the query will output the titles found.

SPARQL via POST urlencoded

In order to send the SPARQL query a client must follow these steps:

1. Encode the query as a URL, for the previous query example:

PREFIX%20td%3A%20%3Chttps%3A%2F%2Fwww.w3.org%2F2019%2Fwot%2Ftd%23%3E%20%0APREFIX%20dc%3A%20%3Chttp%3A%2F%2Fpurl.org%2Fdc%2Fterms%2F%3E%0ASELECT%20%3Ftitle%20%7B%0A%09%3Fs%20dc%3Atitle%20%3Ftitle%20.%0A%7D

2. Send a POST request to the SPARQL endpoint codifying the query as a parameter, in addition include the header Content-Type with application/x-www-form-urlencoded:

POST /api/search/sparql?query=PREFIX%20td%3A%20%3Chttps%3A%2F%2Fwww.w3.org%2F2019%2Fwot%2Ftd%23%3E%20%0APREFIX%20dc%3A%20%3Chttp%3A%2F%2Fpurl.org%2Fdc%2Fterms%2F%3E%0ASELECT%20%3Ftitle%20%7B%0A%09%3Fs%20dc%3Atitle%20%3Ftitle%20.%0A%7D

As a result, the query will output the titles found.

SPARQL via POST directly

In order to send the SPARQL query a client must send a POST request to the SPARQL endpoint including the query in the body, in addition include the header Content-Type with application/sparql-query:

POST /api/search/sparql

As a result, the query will output the titles found.