The idea behind the RDF WebAPI is that there are simple, generall available, operations for working with remote RDF databases, particularly publishing RDF data.
Publishing RDF means making it available to other applications and other people, whoever and wherever that might be. The publisher does not usually know who the consumers of the information will be. A publisher of RDF is not building a designed, distributed application, but, like the current web, is putting information up for others to use as they see fit.
Publishing is based on query. RDF databases (that is, sets of statements) can range from small (a vCard - 10's of statements) to large (an interface to a large SQL database - possibly millions of statements). For large RDF models, it is not practical or desirable to transfer the whole model just to read some small amount of data out of it so query is the basis for access.
"Simple" is important because we want the protocol to be generally available so being simple enough for a wide range of implementations is important. While it may not be ideal in every situation, it is hoped this protocol is sufficient useful for wide-scale deployment. Indeed, "protocol" is rather grand - it is a convention for using HTTP, XMLP, or other base protocol. The Joseki core engine is independent of HTTP although the only binding currently provided is to HTTP, using GET for query.
The protocol tries to adhere to web practice (W3C Web Architecture Document):
The RDF WebAPI is a set of operations which treat RDF models as first-class web resources. The most important implication of this is that models have URIs as they are significant web resources.
The basic operations on a model are to retrieve (query) information and to update or add information. Such abstract operations need to be realised by XMLP, HTTP or some other protocol and this choice can as much a factor of the environment as the technical merits of each protocol. Joseki realises the protocol for HTTP.
The operations supported are:
New operations can be added - all operations are handled by modules loaded
through description in the Joseki configuration file. The operations above
form the core set in the distribution which have standard descriptions in the
joseki-defs.n3 file.
The simplest operation is plain GET: reading a whole database
in the way any web server responds to GET, returning the
whole model. More selective queries are given using the HTTP query string:
A fetch request:
GET /model?lang=fetch&r=http://example.org/resource HTTP/1.1 Host: example.org
which will return the RDF statements associated with the named resources. See RDF Data Objects for further details for "fetch".
An RDQL request:
GET /model?lang=RDQL& \
query=SELECT%20*%20WHERE%20(%3fx%20%3fy%20%3fz) HTTP/1.1
Host: example.org
which performs a query specified in RDQL – a single subgraph is
returned. The query string is the encoded form of
"SELECT * WHERE (?x ?y ?z)".
The significant parameter is "lang", which names the query language. This can be the URI for the language or a short name - the examples here use the short name as the URLs produced are shorter. Other parameters depend on the query language.
Occasionally, GET isn't what an application wants. Maybe the query is in dnager of exceeding the practical limits on URL length for GET; maybe the application uses many operations and does not to switch to a different style; may be the application wishes to guarantee the operation goers back to the original source.
Queries can be sent over HTTP POST (assuming the server has been set up to accept such queries). For example:
POST /myModel?query HTTP/1.1
Host: example.org
Content-Type: application/rdf+xml; charset=utf-8
Accept-Charset: utf-8
Accept: application/rdf+xml
...
<?xml version="1.0" encoding="utf-8"?>
<rdf:RDF
xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'
xmlns:rdfs='http://www.w3.org/2000/01/rdf-schema#'
xmlns:joseki='http://joseki.org/2003/07/configuration#'>
<rdf:Description>
<joseki:requestQueryLanguage>RDQL</joseki:requestQueryLanguage>
<joseki:queryScript>
SELECT *
WHERE (?x ?y ?z)
</joseki:queryScript>
</rdf:Description>
</rdf:RDF>
and the body of the POST contains exactly one RDF model. There is a required
property, joseki:requestQueryLanguage, which has a string
value for the language name, and the rest of the model contains the query.
If the query is sent as a (big) string, then the property
joseki:queryScript may be used; the query may also be
structured in the RDF model - it depends on the query language.
The general form:
Target URL, operation, graph => graph
which becomes:
POST /myModel?op=operation HTTP/1.1 Host: example.org Content-type: application/rdf+xml <?xml version="1.0" encoding="utf-8"?> <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:RDF>
And the reply is of the form of a single RDF graph. The HTTP reposnse code indictaes the success, or failure, of the operation.
HTTP/1.1 200 OK Date: Thu, 16 Jan 2003 15:53:25 GMT Server: Jetty/4.2.5 (Windows XP 5.1 x86) Content-Type: application/rdf+xml; charset=utf-8 Connection: close <?xml version="1.0"?> <rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#' xmlns:ex='http://example.com/'> <rdf:Description rdf:about='http://example.com/something'> . . . </rdf:Description> </rdf:RDF>
Implementations of "add" and "remove" are supplied. These take a graph as argument and add or remove it from the target model. The junit test suite adds its own "clear model" operation.