# AllegroGraph 3.3 HTTP Protocol

NOTE: if you start the AllegroGraph server with the `--new-http-port` argument, or use the `:new-http-port` configuration option, then the document you want to read is the new HTTP Server document.

# Table of Contents

## Managing the Server

## Summary of the Sesame 2.0 Protocol

### Retrieve protocol version

### List available repositories

### Submit A Query

### List the contexts in a Triple Store

### Query the Size of a Triple Store

### Query Namespace Definitions

### Add a Namespace Definition

### Delete a Namespace Definition

### Fetch Triples by Pattern

### Update content of triple-store

### Remove triples by pattern

## AllegroGraph Extensions

### Create a New Repository or Access One

### Fetch triples by pattern

### Load N-Triples or RDF from file or URL

### Query index info

### Update indices or info

### Query datatype and property mappings

### Update type and property mappings

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.

- Class: sesame-server
- Function: make-sesame-server
- Function: start-sesame-server
- Function: stop-sesame-server
- Function: export-to-sesame

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.