Here we will explore two RESTful ways of searching for content using Callimachus:

Keyword searches

Keyword searches may be performed on certain RDF properties. See Appendix A for a list of RDF properties that may be searched.

An OpenSearch description document may be discovered by resolving the top-level OPTIONS and looking for the Search URL. Find the link:header with rel="search" (See the section Browsing Content for details). Search results are returned in an Atom document augmented with OpenSearch response elements.

Perform an HTTP GET on the Search URL. Provide an Accept: header including its associated content type. For example:

GET http://example.com/#rel=search HTTP/1.1
Accept: application/opensearchdescription+xml

The equivalent curl command is:

curl -H "Accept: application/opensearchdescription+xml" "http://example.com/#rel=search"

Which will result in:

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
<ShortName>example.com</ShortName>
<Url type="application/atom+xml" template="http://example.com/#rel=search&amp;searchTerms={searchTerms}"/>
</OpenSearchDescription>

You may then perform a subsequent HTTP GET on the Template URL using the content type specified (in the Url tag's template and typeattributes), substituting your search terms for "{searchTerms}". Note that keyword searches require authentication. To actually perform a keyword search on, for example, the word "Callimachus":

GET http://example.com/#rel=search&searchTerms=Callimachus HTTP/1.1
Accept: application/atom+xml
Authorization: Digest username="john", realm="http://example.com/", ...

The equivalent curl command is:

curl --digest --user john -H "Accept: application/atom+xml" "http://example.com/#rel=search&searchTerms=Callimachus"

Results will look like:

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:calli="http://callimachusproject.org/rdf/2009/framework#"
  xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/" xmlns:app="http://www.w3.org/2007/app">
        <id>http://example.com/#rel=search&amp;searchTerms=Callimachus</id>
        <title>example.com:8080</title>
        <updated>2012-02-23T13:55:59.504Z</updated>
        <entry>
                <id>http://example.com/callimachus/images/callimachus-icon.ico</id>
                <link href="http://example.com/callimachus/images/callimachus-icon.ico#rel=alternate&amp;type=html" rel="alternate"
  type="text/html"/>
                <title>callimachus icon</title>
                <updated>2012-02-24T01:25:04.753Z</updated>
                <content src="http://example.com/callimachus/images/callimachus-icon.ico" type="text/xsl"/>
        </entry>
        <entry>
                <id>http://example.com/callimachus/callimachus-ontology.ttl</id>
                <link href="http://example.com/callimachus/callimachus-ontology.ttl#rel=alternate&amp;type=html" rel="alternate"
  type="text/html"/>
                <title>callimachus ontology</title>
                <updated>2012-02-24T01:24:55.979Z</updated>
                <content src="http://example.com/callimachus/callimachus-ontology.ttl" type="text/xsl"/>
        </entry>
        ...
</feed>

See the OpenSearch description for details on the OpenSearch description document syntax and the OpenSearch response elements.

SPARQL queries

The SPARQL Query Language may be used to query RDF content. Requesting Callimachus' SPARQL endpoint via an HTTP GET with an Accept: header of text/html or application/xhtml+xml (as a browser should) will return an HTML form suitable for human-centric queries. The SPARQL endpoint may also be directly used via REST calls as described below.

The location of the SPARQL endpoint may be discovered by resolving Callimachus' VoID description and parsing out its location.

GET http://example.com/.well-known/void HTTP/1.1
Accept: application/rdf+xml

Note that this and other responses may respond with an HTTP 303 (See Other) response directing you to another location via the Location:header:

HTTP/1.1 303 See Other
Location: http://example.com/.well-known/void#rel=describedby
Content-Length: 0
...

Resolve the URL provided there for the canonical location of the VoID description:

GET http://example.com/.well-known/void#rel=describedby HTTP/1.1
Accept: application/rdf+xml

The equivalent curl command is:

curl -L -H "Accept: application/rdf+xml" "http://example.com/.well-known/void"

A typical response looks like:

HTTP/1.1 200 OK
Age:  0
Etag:  W/"5811c8ee-7566acc1"
Last-Modified:  Fri, 24 Feb 2012 14:49:19 GMT
Date:  Fri, 24 Feb 2012 17:14:01 GMT
Content-Type:  application/rdf+xml
Cache-Control:  public,max-age=868
Access-Control-Allow-Origin:  *
content-version:  "5811c8ee"
Content-Encoding:  gzip
Vary:  Accept,Accept-Charset
Content-MD5:  jUThXJZm7pQvWlmF6OKTNw==
Accept-Ranges:  bytes
Content-Length:  423
Server:  Callimachus Server/Callimachus 0.15-SNAPSHOT

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
        xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
        xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
        xmlns:foaf="http://xmlns.com/foaf/0.1/"
        xmlns:void="http://rdfs.org/ns/void#"
        xmlns:audit="http://www.openrdf.org/rdf/2009/auditing#">

<rdf:Description rdf:about="http://example.com/.well-known/void">
        <audit:revision rdf:resource="http://example.com/change/t1358bd5c49cx0"/>
        <rdf:type rdf:resource="http://rdfs.org/ns/void#DatasetDescription"/>
        <rdfs:label>void</rdfs:label>
        <foaf:primaryTopic rdf:resource="http://example.com/.well-known/void#dataset"/>
</rdf:Description>

<rdf:Description rdf:about="http://example.com/.well-known/void#dataset">
        <rdf:type rdf:resource="http://rdfs.org/ns/void#Dataset"/>
        <foaf:homepage rdf:resource="http://example.com/"/>
        <void:sparqlEndpoint rdf:resource="http://example.com/sparql"/>
        <void:rootResource rdf:resource="http://example.com/"/>
        <void:openSearchDescription rdf:resource="http://example.com/#rel=search"/>
        <void:uriSpace rdf:resource="http://example.com/"/>
</rdf:Description>

</rdf:RDF>

The SPARQL endpoint URL is provided in the void:sparqlEndpoint tag.

Use the SPARQL Protocol to perform queries via REST. See the SPARQL Protocol specification for URL parameters and the SPARQL Query Language specification for details of the query language.

curl --digest --user john --data-urlencode query@test.rq -H accept:application/sparql-results+xml http://example.com/sparql
curl --digest --user john --data-urlencode update@test.ru http://example.com/sparql