Tupelo Server Protocol
From Tupelo Wiki
In versions 2.2 and greater, Tupelo provides a server-side implementation based on extensions to Nokia's URIQA (http://sw.nokia.com/uriqa/URIQA.html) protocol. The protocol is specified here.
| Table of contents |
|
|
Architecture
Server-side
Tupelo Server is a servlet that should be hosted in a web application container. It is configured (currently in an unspecified way) to be backed with a single Tupelo Context and all operations requested by the client are performed against that Context.
Client-side
A client Context implementation is provided that translates all supported Operators into requests to a server. The client must be configured with the URL of the servlet representing a Tupelo Server instance. There are no restrictions on what URL can be used.
Non-Java clients must use the protocol directly. Client-side utilities are planned for other languages, but nothing is currently implemented.
URIQA support
Tupelo Server supports URIQA's "semantic web service" model. In that model, URIQA requests (and Tupelo requests that extend URIQA) are issued as HTTP POSTs against a URL identifying the Tupelo Server instance. Tupelo deviates from the URIQA specification in several important ways:
- Tupelo Server does not support the notion of a Concise Bounded Description but instead MGET is extended with a depth parameter that enables arbitrarily-deep subgraphs to be returned regardless of whether the intermediate nodes are blank (at high depths this can be slow depending on the capabilities of the server's backend metadata store.)
- Tupelo Server supports RDF serialization formats in addition to RDF/XML (currently N3 and N-Triples).
- Tupelo Server allows URIQA semantic web service-style methods to be issued against a resource using GET, PUT, and DELETE in addition to POST.
- Tupelo Server provides several additional semantic web service methods including PUT, GET, and DELETE for CRUD (http://en.wikipedia.org/wiki/Create,_read,_update_and_delete) on the resource (not its metadata) as well as MQUERY for issuing complex RDF queries against the backing Context.
Methods
Tupelo Server methods take a variety of parameters. Common ones include:
- uri - the URI of the subject on which to perform the method
- format - the format of the input or output of the method:
- rdf - RDF/XML format
- nt - N-Triples format
- n3 - n3 format
MGET
Retrieves metadata associated with a given RDF subject. Unlike URIQA, the Concise Bounded Description is not returned; instead, all triples with the given subject are returned. If the depth parameter is supplied, all triples within a given number of hops are returned, where a hop means recursively following predicate chains from the subject. In addition to HTTP POST, HTTP GET can be used with "MGET" as the value of the "method" parameter, for equivalent behavior.
Parameters
- URI - the subject URI
- depth - how many hops to follow
- format - the serialization format for the result (xml, nt, n3) - default: xml
Payload
Input body: none
Output body: the serialized RDF subgraph returned by the query
Example
Request:
POST /myservlet?method=MGET&uri=http://test.org/ns#joe&format=n3&depth=2 HTTP/1.1
Response:
HTTP/1.1 200 OK
Content-type: text/plain
Content-length: 298
@prefix _7: <http://test.org/ns#>.
@prefix foaf: <http://xmlns.com/foaf/0.1/>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
_7:joe a foaf:Person;
foaf:knows _7:bethany.
_7:bethany a foaf:Person;
foaf:knows _7:someoneElse.
MPUT
Adds triples to the Context. Unlike URIQA, this allows any triples to be written, whether or not they're associated with the subject specified by the uri parameter. In addition to HTTP POST, HTTP PUT can be used with "MPUT" as the value of the "method" parameter, for equivalent behavior.
Parameters
- format - the serialization format for input (xml, nt, n3) - default: xml
Payload
Input body: serialized RDF triples to add
Example
Request:
POST /myservlet?method=MPUT&uri=http://test.org/ns#joe HTTP/1.1
Content-type: text/xml
Content-length: 254
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#" >
<rdf:Description rdf:about="http://test.org/ns#joe">
<rdfs:label>Joe Futrelle</rdfs:label>
</rdf:Description>
</rdf:RDF>
Response:
HTTP/1.1 200 OK
MDELETE
Removes triples from the Context. Unlike URIQA, this allows any triples to be removed, whether or not they're associated with the subject specified by the uri parameter. In addition to HTTP POST, HTTP PUT and HTTP DELETE can be used with "MDELETE" as the value of the "method" parameter, for equivalent behavior.
Parameters
- format - the serialization format for input (xml, nt, n3) - default: xml
Payload
Input body: serialized RDF triples to remove
Example
Request:
POST /myservlet?method=MDELETE&uri=urn:ignore&format=nt Content-type: text/plain Content-length: 98 <http://test.org/ns#bethany> <http://xmlns.com/foaf/0.1/knows> <http://test.org/ns#someoneElse> .
Response:
HTTP/1.1 200 OK
MQUERY
Issues a query against the Context. Currently the only query syntax supported is sparql, and Tupelo only supports a very restricted subset of SPARQL.
Specifically, two query forms are accepted: SELECT, and CONSTRUCT
[PREFIX pfx: <uri>]*
SELECT var+
WHERE { pattern* }
no additional clauses (e.g., LIMIT) are currently supported for SELECT queries. For CONSTRUCT:
[PREFIX pfx: <uri>]*
CONSTRUCT { pattern* }
WHERE { pattern* }
again, no additional clauses are supported.
Parameters
- syntax - the query syntax (sparql)
- format - the result format (leave unspecified to use a default format)
Payload
Input body: the query
Output body: the results in an appropriate syntax
In the case of SPARQL SELECT queries, the results are available in two formats:
- By default, the SPARQL XML result format, specified here (http://www.w3.org/TR/rdf-sparql-XMLres/);
- If the "format" parameter is set to "json", in a JSON encoding of that format, specified here (http://www.w3.org/TR/rdf-sparql-json-res/). (>2.3 only!)
In the case of SPARQL CONSTRUCT queries, any of the three supported RDF serializations can be used (N3, N-Triples, or RDF/XML)
Example
Request:
POST /myservlet?method=MQUERY&syntax=sparql HTTP/1.1
Content-type: text/plain
Content-length: 156
PREFIX t: <tag:tupeloproject.org,2004:/test/>
SELECT ?parent ?grandparent ?kid
WHERE {
?kid t:hasParent ?parent .
?parent t:hasParent ?grandparent .
}
Response:
HTTP/1.1 200 OK
Content-type: text/xml
Content-length: 1995
<?xml version="1.0" encoding="UTF-8"?>
<sparql xmlns="http://www.w3.org/2005/sparql-results#">
<head>
<variable name="parent"/>
<variable name="grandparent"/>
<variable name="kid"/>
</head>
<results distinct="false" ordered="false">
<result>
<binding name="parent">
<uri>tag:tupeloproject.org,2004:/test/bob</uri>
</binding>
<binding name="grandparent">
<uri>tag:tupeloproject.org,2004:/test/jacques</uri>
</binding>
<binding name="kid">
<uri>tag:tupeloproject.org,2004:/test/joe</uri>
</binding>
</result>
...
<result>
<binding name="parent">
<uri>tag:tupeloproject.org,2004:/test/carolyn</uri>
</binding>
<binding name="grandparent">
<uri>tag:tupeloproject.org,2004:/test/zoe</uri>
</binding>
<binding name="kid">
<uri>tag:tupeloproject.org,2004:/test/joe</uri>
</binding>
</result>
</results>
</sparql>
PUT
Writes data to the blob associated with the specified URI. This method can be used with the HTTP POST or the HTTP PUT method. If the HTTP PUT method is used, the method does not need to be specified as a parameter.
Parameters
- uri - the URI to write to
Payload
Input body: the data
Example
Request:
POST /myservlet?uri=tag:tupeloproject.org,2004:/test/aBlob&method=PUT HTTP/1.1 Content-type: application/octet-stream Content-length: 18 This is some data.
Response:
HTTP/1.1 200 OK
GET
Retrieves the blob associated with the specified URI. As with PUT, either HTTP POST or HTTP GET can be used. If HTTP GET is used, no method need be specified in the URL.
Parameters
- uri - the URI of the blob to read
Payload
Response body: the blob data
Example
Request:
GET /myservlet?uri=tag:tupeloproject.org,2004:/test/aBlob HTTP/1.1
Response:
HTTP/1.1 200 OK Content-type: application/octet-stream Content-length: 18 This is some data.
DELETE
Deletes a blob. As with PUT and GET, either HTTP POST, HTTP DELETE, or HTTP GET can be used. If HTTP DELETE is used, no method need be specified in the URL.
Parameters
- uri - the URI of the blob to delete
Example
Request:
DELETE /myservlet?uri=tag:tupeloproject.org,2005:/test/aBlob HTTP/1.1
Response:
HTTP/1.1 200 OK
