We implement the Sesame 2.0 Remote Repository HTTP Protocol described in
with some extensions described below.
Managing the Server
The AllegroGraph HTTP Server may be run in the Java server executable or in any Lisp image with AllegroGraph loaded. The parameters to the Java server executable are described in the Java Tutorial and Reference. The AllegroGraph HTTP Server is started in a Lisp image by calling the functions make-sesame-server and start-sesame-server.
The following symbols are described in the AllegroGraph 2.2.5 reference.
- Class: sesame-server
- Function: make-sesame-server
- Function: start-sesame-server
- Function: stop-sesame-server
- Function: export-to-sesame
The AllegroGraph 2.2.5 HTTP server is designed to operate by itself or with the AllegroGraph 2.2.5 Java server in the same Lisp invocation. Other Lisp applications should not be running in the same Lisp image, but if they do, they must not reference any exported triple stores or any triple stores opened bt Java applications.
Summary of the Sesame 2.0 Protocol
The URL of a client request consists of several components
<host and port><root path><protocol><parameters>
The <host and port> part is typically something like "http://localhost:8111".
The <root path> part is specified when the server is started. The default server uses the string "/sesame".
The <protocol> part specifies what the request is about. This is the part that is listed in the descriptions that follow.
The <parameters> part may be present in some requests and omitted in some. It may be part of the URL and is separated from the <protocol> part by a "?" character. The <parameters> part may also be sent as the Content of the client request; in that case, the Content-Type must be specified as "application/x-www-form-urlencoded".
Retrieve protocol version
GET /protocol
Reply: 200 "2"
Retrieve protocol version.
List available repositories
GET /repositories
Response: 200
Content-type: application/sparql-results+xml
Reply: XML/SPARQL tuples
The body of the reply is XML/SPARQL tuples with bindings for "uri", "title", "readable", and "writable".
Sample output:
<sparql xmlns='http://www.w3.org/2005/sparql-results#'>
<head>
<variable name='uri'/>
<variable name='id'/>
<variable name='title'/>
<variable name='readable'/>
<variable name='writable'/>
</head>
<results distinct='false' ordered='false'>
<result>
<binding name='uri'>
<uri>http://localhost:8123/sesame/repositories/wine</uri>
</binding>
<binding name='id'>
<literal>wine</literal>
</binding>
<binding name='title'>
<literal/>
</binding>
<binding name='readable'>
<literal datatype='http://www.w3.org/2001/XMLSchema#boolean'>true
</literal>
</binding>
<binding name='writable'>
<literal datatype='http://www.w3.org/2001/XMLSchema#boolean'>true
</literal>
</binding>
</result>
<result>
<binding name='uri'>
<uri>http://localhost:8123/sesame/repositories/trex</uri>
</binding>
<binding name='id'>
<literal>trex</literal>
</binding>
<binding name='title'>
<literal/>
</binding>
<binding name='readable'>
<literal datatype='http://www.w3.org/2001/XMLSchema#boolean'>true
</literal>
</binding>
<binding name='writable'>
<literal datatype='http://www.w3.org/2001/XMLSchema#boolean'>true
</literal>
</binding>
</result>
</results>
</sparql>
Submit A Query
GET /repositories/<ID>
parameters: infer={true|false}
query=<query string>
queryLn={SPARQL|Prolog}
Reply: 200
The current implementation does not support inferencing; therefore, the infer parameter must be omitted, or it must be specified with the value "false".
SPARQL Queries:
The body of the reply to a SPARQL query is encoded as specified in Accept headers. The Accept headers must specify a format compatible with the nature of the SPARQL query:
ASK application/sparql-results+xml text/html
SELECT application/sparql-results+xml text/html
CONSTRUCT application/rdf+xml text/rdf+n3
DESCRIBE application/rdf+xml text/rdf+n3
Prolog Queries:
The result of a Prolog query is a list of results where each result is a list of values corresponding to the list of variables in the query.
The output has the form
(i j) vvvvv .
...
where i is a result index and j is a variable index within a result list; vvvvv is the variable binding expressed in N-Triples notation.
List the contexts in a Triple Store
GET /repositories/<ID>/contexts
Reply: 200 XML/SPARQL tuples "contextID"
The body of the reply is XML/SPARQL tuples with bindings for "contextID".
Query the Size of a Triple Store
GET /repositories/<ID>/size
parameters: context...
Reply: 200 "nnn"
Size of (sub)graph(s).
Query Namespace Definitions
GET /repositories/<ID>/namespaces
Reply: 200 XML/SPARQL tuples "prefix" "namespace"
The body of the reply is XML/SPARQL tuples with bindings for "prefix" and "namespace".
Add a Namespace Definition
PUT /repositories/<ID>/namespaces/<prefix>
body: URL
Reply: 204
Add namespace definition.
Delete a Namespace Definition
DELETE /repositories/<ID>/namespaces/<prefix>
Reply: 204
Delete namespace definition.
Fetch Triples by Pattern
GET /repositories/<ID>/statements
parameters: context...
subj pred obj
infer={true|false}
Reply: 200
The body of the reply is triples encoded as specified in Accept headers.
application/rdf+ntriples
application/rdf+xml
text/rdf+n3 application/x-turtle
Update content of triple-store
PUT /repositories/<ID>/statements
POST /repositories/<ID>/statements :
parameters: context...
subj pred obj
baseURI
contentType header determines how data is specified
Reply: 204
Replace content of triple-store with RDF data (PUT). Update content of triple-store with transactions or RDF data (POST). The contentType header determines how data is specified:
application/x-rdftransaction(POST only) body is XML transactionsapplication/rdf+xmlbody is RDF
Transaction Format
Transactions are XML sub elements of a single outermost `<transaction>` element. The elements are interpreted in the order they appear.
Transaction to Add a Triple
The `<add>` element may have 3 or 4 sub-elements.
The first sub-element specifies the subject of the triple. The second sub-element specifies the predicate of the triple. The third sub-element specifies the object of the triple. The fourth sub-element may be omitted to specify the Null Context, or it can be present to specify a context.
Each of the sub-elements may be a `<uri> element where the content is a URI string; or a <bnode> element where the content is an id string (this string is ignored by AllegroGraph); or a <literal>` element where the content is the sting value of the literal. The <literal> element may have the attribute xml:lang to specify a language tag, or the attribute datatype` to specify a data-type for the literal.
The fourth (context) sub-elements may also be the empty element `<null/>` to specify the Null Context.
Transaction to Delete Triples from All Contexts
The `<remove>` element may have up to 3 sub-elements. The sub-elements specify the subject, predicate and object of the triples to be removed. Each sub-element is specified as in the <add> transaction. Each sub-element may also be the empty element <null/> to specify a wildcard that matches any value. If a sub-element is omitted it is treated as <null/>`.
All the matching triples are deleted from the triple store.
Transaction to Delete Triples in Specified Contexts
The `<removeFromNamedContext> elements may have up to 4 sub-elements. The first three specify subject, predicate and object, in that order like in the <remove> element. If specified as <null/>`, the sub-element denotes a wildcard.
The fourth element specifies a context. If specified as `<null/>`, the sub-element denotes the Null Context.
If a sub-element is omitted it is treated as `<null/>`.
Transaction to Delete All Triples
The `<clear> element may be empty to specify the deletion of all triples, or it may contain one sub-element to specify a context to be cleared. If specified as <null/>`, the sub-element denotes the Null Context.
Transaction to Define a Namespace Prefix
The `<setNamespace/> element is always empty. The prefix attribute specifies a prefix, and the name` attribute specifies a URI string.
Transaction to Delete a Namespace Prefix
The `<removeNamespace/> element is always empty. The prefix` attribute specifies a prefix.
Remove triples by pattern
DELETE /repositories/<ID>/statements
parameters: context...
subj pred obj
Reply: 204
Remove triples by pattern.
AllegroGraph Extensions
Create a New Repository or Access One
POST /repositories
parameters: id
readable={true|false}
writable={true|false}
if-exists={error|open|supersede}
name
directory
title
Create a new repository.
The id parameter is required and must be unique.
The name parameter defaults to id.
The directory parameter is relative to the default directory of the server.
The readable and writable parameters default to true.
Fetch triples by pattern
GET /repositories/<ID>/statements
parameters: objend cxend
Fetch triples by pattern.
The extended parameters allow range queries.
If cxend is specified, then one context parameter is required
and additional context parameters are not allowed.
Load N-Triples or RDF from file or URL
PUT /repositories/<ID>/load
POST /repositories/<ID>/load
parameters: ntriple...
rdf...
context...
Load N-Triples or RDF from file or URL.
Each N-Triple or RDF parameter must be a URL with file or internet scheme.
File URLs must denote files visible to the server.
Query index info
GET /repositories/<ID>/index
Reply: 200
The body of the reply is XML/SPARQL tuples with bindings for "unindexedCount", "chunkCount", "unindexedThreshold", "chunkThreshold", and "indexFlavor"
Update indices or info
POST /repositories/<ID>/index
parameters: unindexedThreshold
chunkThreshold
clear={true|false}
indexFlavor...
index={new|all}
Update indices or info.
The unindexedThreshold parameter specifies the number of unindexed triples that trigger an automatic indexing of the triple-store; A value of zero suppresses automatic indexing.
Each indexing operation adds a new index chunk. The chunkThreshold parameter specifies the number of index chunks that trigger an automatic merging of all index chunks into a single index; A value of zero suppresses automatic merging.
If the clear parameter is true, then the current index flavors are discarded. The indexFlavor parameters specify the index flavors to be added to the triple-store. Index flavors are described in the General AllegroGraph Reference.
Query datatype and property mappings
GET /repositories/<ID>/map
Reply: 200 XML/SPARQL tuples "URL" "type"
The body of the reply is XML/SPARQL tuples with bindings for "propertyURL", "datatypeURL", and "type".
Update type and property mappings
POST /repositories/<ID>/map
parameters: datatypeURL
datatypeEncoding
propertyURL
propertyEncoding
clear={true|false}
Reply: 204
Update type and property mappings.