HTTP Protocol | AllegroGraph 3.3

We implement the Sesame 2.0 Remote Repository HTTP Protocol as described in with some extensions described below.

Managing the Server

The AllegroGraph HTTP Server may be run in the standalone AllegroGraph server executable or in any Lisp image with AllegroGraph loaded. The parameters to the AllegroGraph server executable are described in the Java Tutorial. 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 3.3 reference.

The AllegroGraph 3.3 HTTP server is designed to operate by itself or with the AllegroGraph 3.3 direct 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 by client 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}  
             limit=nnn  
 
Reply: 200

The limit parameter applies only to Prolog queries.

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.

If the limit parameter is specified, then only the specified number of result sets are returned in the reply.

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"

If no contexts are specified, the result is the number of triples in the store. If any context parameters are specified, the result is the total number of triples in all the specified contexts.

Note that counteing the triples in specified contexts may be an expensive operation in a large store.

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

If the subj pred and obj parameters are specified, then the body of the request must be empty; one triple is added for each specified context, or if no contexts are specified then a single triple is added to the null context.

If a body is specified, then the subj pred and obj parameters must be omitted. The contentType header determines how data is specified:

application/x-rdftransaction (POST only) body is XML transactions
application/rdf+xml body is RDF
text/plain body is ntriples

When the body is RDF statements, then the baseURI parameter can specify a base URI.

When the body is ntriples, then the saveStrings parameter controls the behavior if any literals are encoded as a result of a datatype or predicate mapping. If the value is "true" then both the original string and the encoded UPI are stored in the triple store. If the value is "false" then only the encoded UPI is stored.

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 default graph), or it can be present to specify a context (or graph).

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

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...  
    saveStrings  externalFormat  baseURI

Load N-Triples or RDF from file or URL. A PUT operation replaces the content of the triple store. A POST operation updates the content of the triple store.

Each N-Triple or RDF parameter must be a URL with file or internet scheme.

File URLs must denote files visible to the server.

The saveStrings and externalFormat parameters apply to N-Triples operations. The externalFormat parameter specifies how octets in a file must be converted into characters. The saveStrings parameter controls how encoded literals are stored. If "true", then literals encoded as a result of a predicate or datatype mapping are stored in string form and in encoded form. If "false" then only the encoded literal is stored.

The baseURI parameter applies only to RDF sources.

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.

AllegroGraph 3.3 HTTP Protocol

Table of Contents