Queries and Commands

Neither queries nor commands operate on resources identified by the URL. For this reason, these operations are not RESTful. They appear in this section because they share the same HTTP interface with all the RESTful operations.

SPARQL

A SPARQL endpoint on Mulgara attempts to conform to the SPARQL protocol definition for HTTP Bindings. This means that it will respond to a GET request using the following parameters:
  • query: A SPARQL query, encoded for URLs.
  • default-graph-uri: The default graph to use in a SPARQL query that does not contain a FROM clause.
The following parameter extensions are also provided:
  • graph: An alias for the default-graph-uri parameter.
  • format: This overrides the Accept: header. May be one of xml, json, rdfxml or n3.

Unsupported SPARQL

POST queries are not yet supported. Any requests containing the query parameter must be GET requests.

The parameter named-graph-uri is not yet supported.

TQL

This behaves similarly to the SPARQL endpoint, though all queries and commands must be in TQL.

Only queries can appear in a GET. Queries and update commands are both permissible in a POST.

NB: whether a TQL operator is considered a query or not is sometimes less than obvious; for example, the "alias" command may serve as both an update command and as a query, but in both cases it must be sent as a POST. See the documentation for individual operators in the TQL User Guide.

Parameter Encoding

Only the query parameter requires URL encoding. Encoding is easily accomplished with the java.net.URLEncoder class.

For example, to select everything from the graph "test:data", the following code may be used:

1   String query = "select * where { ?s ?p ?o }";
2   String encodedQuery = java.net.URLEncoder.encode(query, "UTF-8");
3   URL url = new URL("http://localhost:8080/sparql/?query=" + encodedQuery
4                     + "&default-graph-uri=test:data");

Giving the result:

  http://localhost:8080/sparql/?query=select+*+where+%7B+%3Fs+%3Fp+%3Fo+%7D&default-graph-uri=test:data

Note: the path /sparql/ ends in a slash (/). Not all clients can handle the redirection given if the slash is omitted.

Output

By default, the output of a query is in XML. On the SPARQL interface this will use the SPARQL/XML schema from the SPARQL protocol, and on the TQL interface this will use the TQL/XML schema.

The exception is for SPARQL CONSTRUCT queries. These queries return RDF/XML by default.

If an Accept: header is present in the request, then the following values will override the default behavior:
  • application/sparql-results+xml: Returns data as SPARQL/XML, unless the query is a CONSTRUCT in which case it will return RDF/XML.
  • application/sparql-results+json: Returns data in JSON format.
  • application/rdf+xml: Returns CONSTRUCT queries as RDF/XML. All other results will be SPARQL/XML.
  • text/rdf+n3: Returns CONSTRUCT queries as N3. All other results will be SPARQL/XML.
A query parameter of format will override the Accept: header:
  • xml: equivalent to Accept: application/sparql-results+xml
  • json: equivalent to Accept: application/sparql-results+json
  • rdfxml: equivalent to Accept: application/rdf+xml
  • n3: equivalent to Accept: text/rdf+n3

HTTP Methods

GET

Described above. Results for success will be 200 (OK).

HEAD

Not implemented.

To do: Return the size of the result that would be returned for a GET. HTTP says that this SHOULD be the same as the header of a GET response, but in this case it is not feasible.

POST

Same as GET for queries. Also accepts TQL update commands. Update commands return 204 (No Content).

PUT

Not implemented.

DELETE

Not implemented.