The SPARQL service interface is a contract between RDF data access producers and consumers.
input to the RDF Data Access WG
The SPARQL service interface is a contract between RDF data access
producers and consumers. RDF Data Access Use Cases and
Requirements[UCR] discusses examples such as
searching for email addresses from a personal information management service.
To look at a similar, more concrete example, suppose such a service is
available at http://pim.example/data. Then, using SPARQL query
language[QL], we write the question where is
Johnny Lee Outlaw's blog? as...
PREFIX foaf: <http://xmlns.com/foaf/0.1/> SELECT ?pg WHERE (?who foaf:name "Johnny Lee Outlaw") (?who foaf:weblog ?pg)
And we encode the query in a URI in the conventional way:
http://pim.example/data?query=PREFIX+foaf%3A+%3Chttp%3A%2F%2Fxmlns.com%2Ffoaf%2F0.1%2F%3E%0D%0ASELECT+%3Fpg%0D%0AWHERE%0D%0A++%28%3Fwho+foaf%3Aname+%22Norm+Walsh%22%29%0D%0A++%28%3Fwho+foaf%3Aweblog+%3Fpg%29%0D%0A
We expect results such as the following:
<sparql xmlns="http://www.w3.org/2001/sw/DataAccess/rf1/result">
<head>
<variable name="pg"/>
</head>
<results>
<result>
<pg uri="http://blog.outlaw.example/"/>
</result>
</results>
</sparql>
This is one example. The general case is specified in the following sections. The key words must, must not, required, shall, shall not, should, should not, recommended, may, and optional in this document are to be interpreted as described in [RFC2119].
A service target IRI[IRI] t is combined with a SPARQL query string qs using the conventional encoding, using query as the parameter name. The exact algorithm for encoding the query is given in section 11.6 Serialization as application/x-www-form-urlencoded of [XForms] and the algorithm for combining the encoded parameters with t is given in section 11.9 The get Submit Method.
The server should make available representations of the resource identified by the resulting IRI; in the case of an HTTP IRI, for example, responding to GET requests with 200 OK responses (or redirection 3xx or authentication/payment 4xx responses leading to 200 OK responses).
The server may respond to POST requests with parameters in the body similarly, to allow for queries that exceed practical IRI length limitations.
The results of a query are determined by an RDF Dataset chosen by the server in combination with the query supplied in the request. Note the WITH and FROM clauses in section 9 Specifing RDF Datasets of [QL]:
The WITH clause gives URIs that the query processor can use to create the background graph and the FROM clause can be used to specify named graphs. A query processor may use these URIs in any way to associate an RDF Dataset with a query. For example, it could use URIs to retrieve documents, parse them and use the resulting triples as one of the graphs; alternatively, it might only service queries that specify URIs of graphs that it already has stored.
See also [SADDL@], a vocabulary for describing services, including the RDF Datasets they use.
To dereference the URI from the example above, a consumer may send this HTTP 1.1 request (cf section 5 HTTP Request of [HTTP]):
GET /data?query=PREFIX+foaf%3A+%3Chttp%3A%2F%2Fxmlns.com%2Ffoaf%2F0.1%2F%3E%0D%0ASELECT+%3Fpg%0D%0AWHERE%0D%0A++%28%3Fwho+foaf%3Aname+%22Norm+Walsh%22%29%0D%0A++%28%3Fwho+foaf%3Aweblog+%3Fpg%29%0D%0A HTTP/1.1 Host: pim.example
and the result should be:
200 OK
Content-Type: application/xml
<sparql xmlns="http://www.w3.org/2001/sw/DataAccess/rf1/result">
<head>
<variable name="pg"/>
...
In cases like this, where the client does not specify acceptable content types:
The client may specify other acceptable content types, such as turtle[@@ref], using the Accept: header (cf section 14.1 Accept of [HTTP]) and the server should use the highest quality acceptable type in response.
Note that the server may return 406 (not acceptable) or it may return 200 OK using a type that the client did not specify as acceptable.
If the value of the query parameter is not a correct SPARQL query, the server must not return 200 OK; it should give a 400 (bad request) response.
A server may relay warnings using the Warning header specified in section 14.46 Warning of [HTTP].
A server may respond with any of the 5xx HTTP responses: 500 Internal Server Error, 501 Not Implemented, 502 Bad Gateway, 503 Service Unavailable, etc.
The client may specify a limit parameter, which is a sequence of digit characters that represent a non-negative integer. The server should include no more than the limited number of solutions in its response.
This is an alternative to specifying a LIMIT clause in the query. If both a limit parameter and a LIMIT clause are given, the server should use the lower limit. or should the protocol param override? kinda arbitrary
Normative:
Informative:
fodder for the Bibliography generator:
UCR http://www.w3.org/TR/2004/WD-rdf-dawg-uc-20041012/ QL http://www.w3.org/TR/rdf-sparql-query/ VBR http://www.w3.org/TR/2004/WD-rdf-sparql-XMLres-20041221/ XForms http://www.w3.org/TR/2003/REC-xforms-20031014/