Interacting with a HeFQUIN Service

After starting a HeFQUIN service (which you can do either using Docker, using a servlet container embedded in HeFQUIN, or using your own, separate servlet container), you can first test it by opening http://localhost:8080/ in a Web browser (assuming that you have started the service at port 8080). If this works (i.e., you see a page that describes the service), you can start interacting with the service via HTTP. In particular,

While the following sections describe these options in detail, we also provide an OpenAPI documentation of the API of the HeFQUIN service. This documentation is also available at the root endpoint of the service: http://localhost:8080/ (assuming that you have started the service at port 8080).

Issuing Queries

At the address http://localhost:8080/query the HeFQUIN service provides a SPARQL endpoint via which clients can issue SPARQL queries to be executed over the federation for which the service has been set up. To this end, the client may send a GET request or a POST request.

In the case of a GET request, the query needs to be provided in URL-encoded form via the URL parameter query (the URL parameters default-graph-uri and named-graph-uri, as introduced for SPARQL endpoints, are not supported by the HeFQUIN service).

In a POST request, the (unencoded) query may be provided directly in the request body, in which case the request header must contain a Content-Type field with application/sparql-query as value. Alternatively, the request body of the POST request may contain the query parameter with the URL-encoded query as value, in which case the value of the Content-Type field in the request header must be application/x-www-form-urlencoded (also for POST requests, the URL parameters default-graph-uri and named-graph-uri are not supported by HeFQUIN).

For instance, by using the command-line tool curl, you may execute the following command to issue the query in a file called ExampleQuery.rq. 


curl -X POST http://localhost:8080/sparql \
    --data-binary @ExampleQuery.rq \
    -H 'Content-Type: application/sparql-query'

In any case (using GET requests or POST requests), the client may specify the format in which it wants to receive the query result in the response. To this end, the client may include an Accept field in the request header, using any of the following media types (with the first being used as the default).

Responses returned by the HeFQUIN service may use any of the following HTTP status codes.

Inspecting Query Processing Details

The HeFQUIN service also provides a diagnostic endpoint at http://localhost:8080/query-inspect, which can be used to inspect internal processing details of a given query, including the logical and physical query plans, execution times, and other statistics. This functionality is intended for debugging, performance tuning, and query analysis.

The endpoint /query-inspect supports both GET and POST requests using the same content types and parameters as the /sparql endpoint.

For instance, by using the command-line tool curl, you may execute the following command to issue the query in a file called ExampleQuery.rq and retrieve information about the resulting query execution process. 


curl -X POST http://localhost:8080/query-inspect \
    --data-binary @ExampleQuery.rq \
    -H 'Content-Type: application/sparql-query'

The service will return a response in JSON format, with application/json as the content type.

Responses returned by the service may use any of the following HTTP status codes.

If the request is valid, the response will include:

Below follows an example of the structure of the output that can be expected. 


{
    "queryMetrics": {
        "overallQueryProcessingTime": 222,
        "planningTime": 3,
        "compilationTime": 1,
        "executionTime": 200,
        "queryPlanningStats": { ... },
    	"executionStats": { ... },
        "physicalPlan": "(physical plan representation)",
        "logicalPlan": "(logical plan representation)",
        "sourceAssignment": "(source assignment)",
        "exceptions": [ ]
    }
}