This is a tutorial to help you get started with qSAC, the
Quaestor-based implementation of the
SAC interface. The SAC interface
makes heavy use of content negotiation
of MIME types, and so
you may want to have the documentation on
MIME types ready to hand.
You can download the server either as a Tomcat .war
servlet, or as a standalone (Jetty-based) server, from
the project's
download site at Google code. See the
installation notes for more detail.
In the discussion below, we'll assume that you're using the
standalone server, and so prefix our URLs with
http://localhost:8080, but you should see exactly the
same behaviour if you're using a different port or using the Tomcat
servlet, but relative to the appropriate URL.
We'll use curl, the command-line HTTP client, to
manipulate and query the SAC; you can obviously work with any tool
which can generate the appropriate HTTP interactions. There's a
friendly client on the way.
The first thing you have to do is to create a SAC. To do this, you
have to pick a name for your SAC – we'll use mysac – and
you have to supply some metadata which describes the SAC. This
metadata might be purely descriptive, or might include configuration
information to indicate how the SAC delegates queries, or how it
handles persistence. For more details, see
the metadata documentation.
The metadata we'll set is very simple (the following is RDF in Turtle or Notation3 format; you can also use the XML-like RDF/XML form).
@prefix dc: <http://purl.org/dc/elements/1.1/>. <> dc:description "My SAC"; dc:creator "Norman".
Notice that we refer to the SAC as just <>.
Since the RDF is parsed with the PUT address as its base-URI, this is
the most compact way to name the SAC.
Put this RDF into a file called, say, metadata.ttl,
and PUT it to the service:
% curl --upload-file metadata.ttl -H content-type:text/turtle \
http://localhost:8080/sac/mysac
You should get back some HTML indicating that the SAC named
http://localhost:8080/sac/mysac has been
created successfully (it's useful to include one of the
--include or --verbose options in the above
command, and see the interaction and the response status in more or
lots more detail). You can now go to the
http://localhost:8080/sac page to see the new SAC
mentioned, and can GET the metadata back with another curl command:
% curl 'http://localhost:8080/sac/mysac?metadata'
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/elements/1.1/" >
<rdf:Description rdf:about="http://localhost:8080/sac/mysac">
<dc:creator>Norman</dc:creator>
<dc:description>My SAC</dc:description>
</rdf:Description>
</rdf:RDF>
If you fancy a bit of variety, you can specify the format you want
the response to be in, by using the HTTP Accept request header.
% curl -H accept:text/turtle \
'http://localhost:8080/sac/mysac?metadata'
@prefix dc: <http://purl.org/dc/elements/1.1/> .
<http://localhost:8080/sac/mysac>
dc:creator "Norman" ;
dc:description "My SAC" .
SACs are persistent by default: that is, if you do not explicitly delete them before shutting down a SAC server, they will be there when you start it up again. If you want a SAC to be transient, so that it disappears when the server does, then you should declare in the SAC's creation metadata that the SAC model should be transient:
@prefix dc: <http://purl.org/dc/elements/1.1/>. @prefix quaestor: <http://ns.eurovotech.org/quaestor#>. <> dc:description "My SAC"; dc:creator "Norman"; a quaestor:TransientModel.
As of release 0.3, there's no security on the SAC server, so anyone can create and delete SACs. Access control will appear in the fullness of time.
So, we've got a SAC – now we want to add some claims to it.
As discussed on the SKUA wiki, there are multiple possible types of claim. At present, the form of the claims is still uncertain, but they should look something like the following (the SKUA namespace here is currently a dummy).
@prefix skua: <http://myskua.org/claimtypes/1.0/> .
@prefix dc: <http://purl.org/dc/elements/1.1/> .
<> a skua:bookmark;
dc:creator "Norman";
skua:ref [
a skua:webpage;
skua:url <http://myskua.org>;
dc:title "The SKUA project";
];
skua:tag "semanticweb", "rdf", "sparql";
skua:time "2008-01-21T18:11:58Z" .
Note that we haven't include a Turtle @base directive,
and we've referred to the claim with the empty URL
<>. Put that into a file called, say,
claim.ttl, and add this claim to our SAC by POSTing
the file to the SAC's URL, as follows.
% curl --include -H content-type:text/turtle \
--data-binary @claim.ttl \
http://localhost:8080/sac/mysac
HTTP/1.1 201 Created
Content-Type: text/html; charset=utf-8
Location: http://localhost:8080/sac/mysac/claim/0
Transfer-Encoding: chunked
Server: Jetty(6.1.7)
[...]
Notice that the URI for the newly-created claim is returned in the
response's Location header.
The RDF is resolved with a base-URI which corresponds to the
newly-created claim – this is why the empty URI <>
can stand for the claim itself. If the RDF you upload is empty, or if
it does not mention the new claim (because you do not refer to
<>), then that is an error.
If you now GET the SAC URL
http://localhost:8080/sac/mysac, you will see your claim
returned. If you add the Accept:text/turtle
header to the request, you'll see it in Turtle.
Now we have a claim, we can query the SAC.
You query the SAC using the standard RDF query language SPARQL. Let's find all the claims which mention the SKUA web page: the SPARQL query for that would be
prefix skua: <http://myskua.org/claimtypes/1.0/>
prefix dc: <http://purl.org/dc/elements/1.1/>
select ?name ?claim
where {
?claim dc:creator ?name.
?claim skua:ref [ skua:url <http://myskua.org> ].
}
Put that into a file called query.rq and POST it to
the SAC with the correct content-type for SPARQL queries:
% curl -H content-type:application/sparql-query \
--data-binary @query.rq http://localhost:8080/sac/mysac
What comes back is XML with a content-type of
application/sparql-results+xml.
If you want one of the non-default content-types (see the
interface documentation), for example
text/csv, then you can request that using the
Accept header.
You can also make SPARQL queries by url-encoding the query and
GETting it with a ?query= URL parameter, but in many
cases that will be more fuss than simply posting the query with the
correct MIME type.
Once you've finished with the SAC, you can delete it from the
server with the HTTP DELETE method.
% curl -X DELETE http://localhost:8080/sac/mysac