Joseki: RDF WebAPI

The idea behind the RDF WebAPI is that there are simple operations for working with remote RDF models, 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 models (sets of statements) can range from small (say - a vCard - 10's of statements) to large (say - 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, it is hoped this protocol is sufficient. Indeed, "protocol" is rather grand - it is a convention for using HTTP.

Style

The protocol adheres to web practice (W3C Web Architecture Document):

Models have URLs
Models are accessible over HTTP to that URL
Reading information is achieved by HTTP GET
Operations are graph-centric: they exchange subgraphs of the target model.

Overview of the RDF WebAPI

The RDF NetAPI 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 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.

There are three classes on operations:

Operations on the contents of a model
QueryModel(URI, query language, query) => Serialized RDF data
UpdateModel(URI, changes)
Operations on whole models
GetModel(URI) => Serialized RDF data
PutModel(URI, serialized RDF data) => <void>
Operations that give information about the capabilities of a model or the server itself:
Options(*) => server capabilities
Options(URI) => capbabilties

Joseki provides query of a model, GETting a model, Options, ping and some update operations.

Query: HTTP GET

The simplest operation is plain GET: reading a whole model 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 http://host/model?lang=fetch&r=http://example.org/resource HTTP/1.1

which return the RDF statements asscoaited with the named resources. See RDF Data Objects for further details.

An RDQL request:

GET http://host/model?lang=RDQL& \
  query=SELECT%20*%20WHERE%20(%3fx%2c%20%3fy%2c%20%3fz) HTTP/1.1

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. Other parameters depend omn the query language.

Query: HTTP POST

Occasionally, GET isn't what an application wants. Maybe the query is too large to fit in the URL for GET, maybe the application uses many operations and does not to switch to a different style, maybe the query language naturally has a form as an RDF graph which is tricky (not impossible) to encode as a single string.

Queries can be sent over HTTP POST (assuming the server has been set up to accept such queries). For example:

POST http://host/myModel?query HTTP/1.1
Content-type: application/rdf+xml
...

<?xml version="1.0" encoding="ISO-8859-1"?>

<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.

Other Operations

The general form:

Target URL, operation, graph=> graph

which becomes:

POST http://host/myModel?op=operation HTTP/1.1
Content-type: application/rdf+xml

<?xml version="1.0" encoding="ISO-8859-1"?>

<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
Connection: close

<rdf:RDF
   xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'
   xmlns:NS0='http://example.com/'>
<rdf:Description rdf:about='http://example.com/something'>
 . . .
</rdf:Description>
</rdf:RDF>

Add and Remove

Implementations of "add" and "remove" are supplied. These take a graph as argument and add or remove it from the target model.