Quaestor: The RESTful HTTP interface

Quaestor has two interfaces, this RESTful HTTP one, which is the main one, and a separate XML-RPC interface (still rather preliminary).

In the documentation below, hostport refers to the machine and port number hosting the Quaestor service, such as localhost:8080.

You interact with Quaestor by creating a knowledgebase with a PUT command, then PUTting ontologies into the knowledgebase, then POSTing SPARQL queries. The front page points to a demo/walkthrough.

The HTTP verbs

GET methods

GET http://hostport/quaestor/kb
Retrieve an information page, reporting on the knowledgebases currently available.
GET http://hostport/quaestor/kb/kb-name[/sm-name]

Retrieve either the complete kb-name model, or the named sm-name submodel. The format of the response is controlled by the Accept header, which if present must contain one of the following MIME types (see note):

You can add an optional query ?model or ?metadata to retrieve the appropriate thing; the default is to retrieve the model.

This method returns status 200 (OK) on success, or a 4xx code on error.

GET http://hostport/quaestor/kb/kb-name?query=query
Perform the SPARQL query which is URL-encoded in the string query. This has the same response codes and accept headers as the POST method below.

PUT methods

PUT http://hostport/quaestor/kb/kb-name

Create a new knowledgebase named `kb-name'. The request content contains the metadata for the knowledgebase. This can be expressed as RDF (with MIME types text/rdf+n3 or application/rdf+xml). For example the body might be:

@prefix dc: <http://purl.org/dc/elements/1.1/>.
<> dc:description "My knowledgebase";
    dc:creator "Norman".

Alternatively, the content can have a text/plain MIME type, which in this context means that the knowledgebase will be given a dc:description whose subject is the given text. For fuller details see below.

It is an error if the knowledgebase already exists. Returns status 204 (No Content) on success, and a 4xx error message if the knowledgebase already exists or if there is some other error.

PUT http://hostport/quaestor/kb/kb-name/sm-name

Upload the request body as the content of the submodel named sm-name, replacing any pre-existing content. The request may have a Content-Type header indicating the format of the body, which, if it is present, must be one of the following MIME types (see note):

If there is no Content-Type header present, the content is parsed as application/rdf+xml.

The request may have a query appended, which may be ?abox, ?instances (which is equivalent to ?abox) or ?tbox. This indicates the type of the corresponding model. The default, if no such query is given, is tbox (I'm not sure how legit this use of query is -- this might change).

Notation3 may also be uploaded using the deprecated MIME type application/n3.

PUT http://hostport/quaestor/kb/kb-name/sm-name?metadata
Set the metadata for a submodel.

POST methods

POST http://hostport/quaestor/kb/kb-name

Takes a SPARQL query as the request body, which should be posted with the Content-Type set to application/sparql-query. The request may be accompanied by an Accept header to control the format of the returned data; the MIME types recognised are the same as for the GET request above.

Returns status 200 (OK) on success, and 4xx otherwise.

POST http://hostport/quaestor/kb/kb-name/sm-name
The content must be one of the RDF MIME types as noted above. The RDF content is added to the named submodel.
POST http://hostport/quaestor/code
Eval the request body as Scheme code. This is only possible if the server has been configured to permit it.

DELETE methods

DELETE http://hostport/quaestor/kb/kb-name
Remove the named knowledgebase. Returns status 204 (No Content) if it successfully removed the knowledgebase, or a 4xx response if there was no such knowledgebase to remove.
DELETE http://hostport/quaestor/kb/kb-name/submodel
Remove the named submodel. Returns status 204 (No Content) if it successfully removed the submodel, or a 4xx response if there was no such knowledgebase, or no such submodel.

Delegation of knowledgebases

Quaestor supports a simple form of query delegation. A knowledgebase can be configured, using the metadata below, to forward queries to another SPARQL endpoint.

The delegation is rather simple-minded. If the metadata of a knowledgebase A includes a triple of the form <A> quaestor:delegatesTo <B>, then when a query is made against knowledgebase A, the same query is made against B (and against any other objects of the same property relation) and the results of the queries against A and B are concatenated. This works adequately if the knowledgebases have similar and independent information, but it fails to answer queries where the relevant triples are in the union of the knowledgebases A and B, but not in either knowledgebase separately.

The object of the quaestor:delegatesTo property may be the URL of another knowledgebase in the same Quaestor instance, or it may be a separate SPARQL endpoint. In the latter case, Quaestor presumes that for a SPARQL endpoint URL http://foo, the query can be made with a GET on the URL http://foo?query=<query>, where <query> is the URL-encoded version of the original SPARQL query. This interface is not standardised, but it appears to be rather common, and is the same as Quaestor's GET-query interface.

Knowledgebase metadata

When you create a knowledgebase with a PUT http://hostport/quaestor/kb/kb-name, as shown above, you can include metadata to describe and configure it. The resources are resolved using the knowledgebase's own URI as the base-URI.

You can add any metadata you like, but some properties are treated specially. The following classes and properties are in the namespace http://ns.eurovotech.org/quaestor# (at present, this might change).

Class quaestor:Knowledgebase
A Quaestor knowledgebase
Class quaestor:ReasonerSpecification
A specification of various required properties of the reasoner to be used with this knowledgebase.
Property quaestor:requiredReasoner
A property of a knowledgebase, which has a quaestor:ReasonerSpecification as its range.
Property quaestor:level
A property of a quaestor:ReasonerSpecification which indicates the functionality required of the reasoner for this knowledgebase. The property may have the values indicated below.
Property quaestor:delegatesTo
A property of a knowledgebase, indicating the URL of another SPARQL endpoint, to which queries can be forwarded, as discussed above.

The available reasoners are as follows:

none
Do not use a reasoner (the default)
simpleRDFS, defaultRDFS, or fullRDFS
Three Jena reasoners supporting RDFS reasoning (able, for example, to reason that rdfs:subClassOf is transitive).
defaultOWL
The default Jena OWL reasoner.
miniOWL and microOWL
The two alternative Jena OWL reasoners.

For fuller details of these reasoners, see the Jena inference documentation.

The formal declaration of these properties is below.

@prefix : <http://ns.eurovotech.org/quaestor#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.

:Knowledgebase a rdfs:Class;
    rdfs:comment "A Quaestor knowledgebase".

:ReasonerSpecification a rdfs:Class;
    rdfs:comment """Specification of the reasoner required to handle
        a knowledgebase""".

:requiredReasoner a rdf:Property;
    rdfs:domain :Knowledgebase;
    rdfs:range :ReasonerSpecification;
    rdfs:comment "The reasoner required to process a specific knowledgebase".

:level a rdf:Property;
    rdfs:domain :ReasonerSpecification;
    rdfs:range xsd:string;
    rdfs:comment """A string indicating reasoning capability.  It may
        be one of the strings:
        none (do not use a reasoner),
        simpleRDFS, defaultRDFS, fullRDFS (three Jena reasoners),
        defaultOWL (the default Jena OWL reasoner),
        miniOWL, microOWL (the two alternative Jena OWL reasoners)""" .

:delegatesTo a rdf:Property;
    rdfs:domain :Knowledgebase;
    rdfs:comment """A SPARQL endpoint to which this knowledgebase should
        delegate queries""" .

If no level property is available, the default reasoner is (currently) none.

Example

For example a configuration file such as the following, sent as the payload of the PUT which creates the knowledgebase, would set up the knowledgebase with a reasoner that could process a useful subset of RDFS.

@prefix dc: <http://purl.org/dc/elements/1.1/>.
@prefix quaestor: <http://ns.eurovotech.org/quaestor#>.

<> dc:description "UCD knowledgebase";
    dc:creator "Norman";
    quaestor:requiredReasoner [
        quaestor:level "simpleRDFS"
    ].