# Joseki: RDF WebAPI

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.

## Style

The protocol tries to adhere 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 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:

1. GET (a simple query that retruns the whole model).
2. Query, for various query languages
3. Update operations
   - Add
   - Remove
4. Ping

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.

## Query: HTTP GET

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.

## Query: HTTP POST

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.

## Other Operations

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>

### 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. The junit test suite adds its own "clear model" operation.