# AllegroGraph 3.3 - (new) HTTP server

# Table of Contents

## Overview

## Conventions

## Example session

## Services provided

## RDF-Transaction data format

## Common Lisp Programming interface

The AllegroGraph HTTP server provides access to AllegroGraph triple stores through an HTTP interface. It is based on the Sesame HTTP protocol, but provides a number of extensions.

## Overview

The server described in this document can be used to publish one or more directories, each containing any number of AllegroGraph triple stores, through an HTTP interface. Such directories are called 'catalogs'. A user that has access to a catalog can create, read from, write to, and delete the stores in that catalog's directory.

The server can be run from a Common Lisp image (see the programming interface), or from the AllegroGraph server (see the new-http options to configure a port and one or more catalog directories).

## Conventions

Usually, you'll want to access the AllegroGraph HTTP services through some client library, but there are also cases where you'll need to write something to directly access the HTTP access points it provides. This section describes the URLs that the server exposes, and their behaviour.

The interface provided by this server is a super-set of the Sesame HTTP interface described in this document.

### Input conventions

Unless noted otherwise, the services that take parameters expect these to be appended to the URL in form-encoded format ― as in `?mail=%3Cmailto%3Alarry%40example.com%3E`. For `POST` requests that send along a `Content-Type` header of `application/x-www-form-urlencoded`, the parameters can also be put in the request body.

A lot of the services expect RDF terms as input. These are written in a format resembling N-triples, with the caveat that non-ASCII character encodings are allowed. Examples of valid terms are `<http://example.com/foo>`, `"literal value"`, `"55"^^<http://www.w3.org/2001/XMLSchema#integer>`.

Any boolean values passed as parameters should be represented by the strings `true` or `false`.

When a server is protected by a username and password, a basic HTTP authentication header should be used to authenticate requests.

### Output conventions

The server always looks at the Accept header of a request, and tries to generate a response in the format that the client asks for. If this fails, a 406 response is returned.

Almost every service is capable of returning `text/plain` and `application/json` responses. Services returning sets of triples (here `text/plain` means N-triples) also support the `application/trix`, `application/rdf+xml`, and `text/rdf+n3`, and `application/x-quints+json` formats, whereas services returning lists or sets of results (SPARQL `select` queries, for example) support `application/sparql-results+xml`.

When encoding RDF triple sets as JSON, arrays of strings are used. The strings contain terms in a format that is basically N-triples with non-ASCII characters allowed (the server always uses UTF-8 encoding). Arrays of three elements are triples (subject, predicate, object) in the default graph, arrays of four elements also contain a graph name (context) as the fourth element. Non-triple result sets use a `{names: [array of strings], values: [array of arrays of n-triples strings]}` format.

The `application/x-quints+json` format works like the JSON triple format shown above, but adds an extra field, the triple ID, to the front of every triple array.

All responses, unless the format disallows it, use UTF-8 character encoding. When asked (using the Accept-Encoding header), the server will gzip or deflate the response body. For typical RDF data, this will make the response a lot smaller.

## Example session

What follows is an example session. For clarity, all headers related to caching, connection keep-alive, and content chunking have been left out.

First, create a repository in the `test` catalog:

    PUT /catalogs/test/repositories/test HTTP/1.1
    Accept: */*
    Content-Type: application/x-www-form-urlencoded

To which the server responds:

    HTTP/1.1 204 No Content

Or, if there was already a store with that name:

    HTTP/1.1 400 Bad Request
    Content-Type: text/plain; charset=UTF-8

    There is already a store named 'test'.

We can now list the repositories in this catalog, asking for JSON content:

    GET /catalogs/test/repositories HTTP/1.1
    Accept: application/json

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=UTF-8

    [{"uri": "<http://localhost:8111/catalogs/test/repositories/test>",
      "id": "\"test\"",
      "title": "\"test\"",
      "readable": "\"true\"^^<http://www.w3.org/2001/XMLSchema#boolean>",
      "writeable": "\"true\"^^<http://www.w3.org/2001/XMLSchema#boolean>"}]

Next, let's add some statements to this store...

    POST /catalogs/test/repositories/test/statements HTTP/1.1
    Accept: */*
    Content-Type: application/json

    [["<http://example.org#alice>", "<http://example.org#name>", "\"alice\""],
     ["<http://example.org#bob>", "<http://example.org#name>", "\"bob\""]]

    HTTP/1.1 204 No Content

Or, doing the same using N-triples instead of JSON:

    POST /catalogs/test/repositories/test/statements HTTP/1.1
    Accept: */*
    Content-Type: text/plain

    <http://example.org#alice> <http://example.org#name> "alice" .
    <http://example.org#bob> <http://example.org#name> "bob" .

To find out Alice's name, we do the following, where [QUERY] is the URL-encoded equivalent of `select ?n {<http://example.org#alice> <http://example.org#name> ?n}`.

    GET /catalogs/ag2/repositories/test?query=[QUERY] HTTP/1.1
    Accept: application/json

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=UTF-8

    {"names":["n"],"values":[["\"alice\""]]}

Or, asking for SPARQL XML results:

    GET /catalogs/ag2/repositories/test?query=[QUERY] HTTP/1.1
    Accept: application/sparql-results+xml

    HTTP/1.1 200 OK
    Content-Type: application/sparql-results+xml; charset=UTF-8

    <?xml version="1.0"?>
    <sparql xmlns="http://www.w3.org/2005/sparql-results#">
      <head><variable name="n"/></head>
      <results>
        <result>
          <binding name="n"><literal>alice</literal></binding>
        </result>
      </results>
    </sparql>

## Services provided

### URL summary

    /catalogs  GET
     /catalogs/<name> prefix for the catalog interface

Services under a catalog URL:

    /protocol  GET
     /repositories  GET
       /<id>  PUT ,  DELETE ,  GET ,  POST
         /size  GET
         /contexts  GET
         /statements  GET ,  DELETE ,  PUT ,  POST
           /delete  POST
         /environments  GET ,  POST ,  DELETE
         /namespaces  GET ,  DELETE
           /<prefix>  GET ,  PUT ,  DELETE
         /freetext  GET ,  POST
         /freetextPredicates  GET ,  POST
         /indices  GET
           /<index>  PUT ,  DELETE
         /indexing  GET ,  POST
           /chunkThreshold  GET ,  PUT ,  DELETE
           /tripleThreshold  GET ,  PUT ,  DELETE
         /functor  PUT   DELETE
         /blankNodes  POST
         /typeMapping  GET ,  PUT ,  DELETE
         /predicateMapping  GET ,  PUT ,  DELETE
         /eval  POST
         /geo
           /types  GET
             /cartesian  PUT
             /spherical  PUT
           /box  GET
           /circle  GET
           /polygon  GET   PUT
           /haversine  GET
         /tripleCache  GET   PUT   DELETE
     /AGVersion  GET

### GET /catalogs

Returns a list of catalogs (by URL) that are available on this server.

### GET <catalog>/protocol

Returns the protocol version used, as an integer. The protocol described in this document is `4`.

### GET <catalog>/repositories

Lists the repositories in this catalog. The result is a set of tuples containing `id` (a literal) and `uri` (a resource) fields. For compatibility with Sesame, there are also fields `readable`, `writeable`, and `title`, but these do not contain relevant information. Stores are always readable and writeable, and title is the same as the ID.

### PUT <catalog>/repositories/<id>

Create a new, empty triple store in a catalog. The `id` may be anything that doesn't contain slashes, backslashes, or tildes.

When one or more `federate` parameters are given, a federated store will be created instead. Each `federate` parameter should contain either the name of another store in this catalog, or a URL to a store on this server, for example `/catalogs/my%20catalog/repositories/x`.

To open a remote store (served from another AllegroGraph server, with the standard, non-HTTP server) pass `host`, `port`, and `file` parameters to this service. This will only work if remote stores are enabled.

### DELETE <catalog>/repositories/<id>

Delete the triple store identified by `id`.

### GET/POST <catalog>/repositories/<id>

This service allows queries to be run against a store. `POST` requests can be used when URL length limitations (say, in a browser) prevent the request to be sent as `GET`, but act exactly the same. This service takes the following parameters:

query
  The query to be executed.
queryLn
  The language of the query. Can be `sparql` or `prolog` . Defaults to `sparql` .
infer
  A boolean value that determines whether reasoning is used when executing the query. Default is `false` .
environment
  The environment to execute the query in. Optional.
context
  Can be passed zero or more times. Sets the graph name, or list of graph names, that will be used by this query. When no context is given, all graphs are used. The string `null` can be used to refer to the default graph of the store.
namedContext
  Also can be given multiple times. Behaves like `context` , except that the named graphs retain their names. Only supported for SPARQL queries.
limit
  An integer. Can be used to limit the amount of results returned by Prolog queries.
$[varname]
  Parameters starting with a `$` character can be used to bind query variables to fixed value (an N-Triples term) when executing the query.
checkVariables
  A boolean that defaults to false, indicating whether an error should be raised when a SPARQL query selects variables that are not mentioned in the query body.

The result formats supported depends on the query. Prolog queries always return tabular data, as do SPARQL `select` queries. `describe` or `construct` queries return triples, and `ask` queries return a boolean value.

### GET <repository>/size

Returns the amount of triples in the repository, as an integer. Takes a single optional argument, `context`, which can be used to restrict the count to a single named graph.

### GET <repository>/contexts

Fetches a list of named graphs in the store. Returns a set of tuples, each of which only has a `contextID` field, which is an N-triples string that names the graph.

### GET <repository>/statements

Retrieves statements (triples) by matching against their components. All parameters are optional ― when none are given, every triple in the store is returned.

subj
  Match a specific subject. When given, should be a term in N-triples format. Can be given multiple times to mean 'the subject must be part of this set of resources'.
subjEnd
  Can only be given if `subj` is given. Matches a range of subjects. Only works if exactly one `subj` parameter is given.
pred
  Match a specific predicate. Can be passed multiple times, like `subj` , to match a set.
predEnd
  Do a range query on predicate.
obj
  Match a specific object. Pass multiple values to match a set.
objEnd
  Range query on objects.
infer
  A boolean. Used to turn on reasoning for this query.
context
  Can be given multiple times. Restricts the query to the given list of named graphs. When not specified, all graphs in the store are used.
limit
  An integer indicating the maximum amount of results to return.

### DELETE <repository>/statements

Deletes triples matching the given parameters. When no parameters are given, every triple in the store is deleted.

subj
  Match a specific subject. When given, should be a term in N-triples format.
pred
  Match a specific predicate.
obj
  Match a specific object.
context
  Match a specific graph name.

### PUT/POST <repository>/statements

This service is used to add statements to a store. When the `PUT` method is used, the store is emptied first, whereas the `POST` method just adds triples.

The `Content-Type` header determines the way the given data is interpreted. Use `text/plain` for N-triples data, `application/rdf+xml` for RDF/XML, `application/json` for JSON data (an array of arrays of strings, with the inner arrays having 3 or 4 elements each), or `application/x-rdftransaction` for a transaction XML document. Unless a `file` parameter is passed, the body of the request is used as input data.

baseURI
  When loading RDF/XML data, the value of this parameter is used as the base URI of the document.
file
  This can be used to load not the body of the request, but a server-side file. Should contain a valid filename.
context
  Used to set the named graph into which the new data is stored.

### POST <repository>/statements/delete

Used to delete a set of statements. Expects a JSON-encoded array of triples as the posted data, and deletes all statements listed in there. `Content-Type` should be `application/json`.

When an `ids` parameter with the value `true` is passed, the request body should contain a JSON-encoded list of triple-ids, instead of actual triples.

### GET <repository>/environments

Environments can be used to restrict certain settings to a specific context. When defining namespaces or Prolog functors, one can choose to define them in an environment instead of globally. Queries can then be executed in such an environment. This service returns a list of names of currently defined environments.

### POST <repository>/environments

Defines a new environment. Takes one parameter, `name`, which is a string that will identify the new environment.

### DELETE <repository>/environments

Delete an environment. Takes a parameter `name` which names the environment that should be deleted.

### GET <repository>/namespaces

List the currently active namespaces, as tuples with `prefix` and `namespace` fields. If an `environment` parameter is given, the namespaces in that environment are returned. If not, you get the top-level namespaces.

### DELETE <repository>/namespaces

Takes an optional parameter `environment`. Deletes all namespaces in that environment, or all top-level namespaces if no parameter is given.

### GET <repository>/namespaces/<prefix>

Returns the namespace URI defined for the given prefix. Can be given an `environment` parameter.

### PUT <repository>/namespaces/<prefix>

Create a new namespace. The body of the request should contain the URI for the namespace, as plain text. Can be given an `environment` parameter to create the namespace in a specific environment.

### DELETE <repository>/namespaces/<prefix>

Delete a namespace. Optionally takes an `environment` parameter.

### GET <repository>/freetext

This is used to perform queries on the free-text indices of the store, if any. A list of matching triples is returned.

pattern
  The text to search for.
infer
  A boolean indicating whether triples that can be derived by reasoning should be included.
limit
  An integer limiting the amount of results that can be returned.

### GET <repository>/freetextPredicates

Yields a list of predicates (RDF resources) that are currently used for free-text indexing.

### POST <repository>/freetextPredicates

Takes one parameter, `predicate`, which should be a resource in N-triples form, and registers this as a free-text indexed predicate. (Note that indexing will only happen for triples added after the predicate was registered.)

### GET <repository>/indices

List the active 'spogi' indices for the store. These are strings like `spogi`, `posgi` etcetera.

### PUT <repository>/indices/<index>

Add an index to the store. The index name should be a five-letter string like `spogi`.

### DELETE <repository>/indices/<index>

Delete an index.

### GET <repository>/indexing

This retrieves the percentage of statements that have been indexed, as a decimal number. For example, `0.75` means that three quarter of the store has been indexed.

### POST <repository>/indexing

Posting to `/indexing` causes the server to index any unindexed triples in the store. The parameter `all`, a boolean which defaults to `false`, can be used to cause all indices to be merged into a single one. This will make things faster, but takes more time.

### GET <repository>/indexing/chunkThreshold

See unmerged chunk threshold in the AllegroGraph documentation. When one is defined, this service can be used to inspect it. Returns an integer, or a 404 response if no threshold is defined.

### PUT <repository>/indexing/chunkThreshold

Set the unmerged chunk threshold. The request body should hold an integer.

### DELETE <repository>/indexing/chunkThreshold

Unset the unmerged chunk threshold.

### GET <repository>/indexing/tripleThreshold

See unindexed triple count in the AllegroGraph reference guide. This fetches this count, or returns a 404 response if none is defined.

### PUT <repository>/indexing/tripleThreshold

Set the unindexed triple threshold. The request body should hold an integer.

### DELETE <repository>/indexing/tripleThreshold

Unset the unindexed triple threshold.

### PUT <repository>/functor

Define a Prolog functor, which can be used in Prolog queries. The body of the request should hold the functor definition, in Lisp syntax, using the `&lt;--` or `&lt;-` operators.

Optionally takes an `environment` parameter, which will cause the functor to be defined in a specific environment.

### DELETE <repository>/functor

Drop a Prolog functor, or all functors. When a `name` parameter is given, the functor by that name is delted. Otherwise, all functors are deleted. Optionally takes an `environment` parameter, to specify which environment should be affected.

### POST <repository>/blankNodes

Cause the server to allocate and return a set of blank nodes. Takes one argument, `amount`, which should be an integer. The service returns a list of `amount` blank nodes.

### GET <repository>/typeMapping

Yields a list of literal types for which type mappings are defined in this store.

### PUT <repository>/typeMapping

Takes two arguments, `type` (the RDF literal type) and `primitiveType`, and defines a type mapping between them.

### DELETE <repository>/typeMapping

Deletes a type mapping. Takes one parameter, `type`, which should be an RDF resource.

### GET <repository>/predicateMapping

Yields a list of literal types for which predicate mappings are defined in this store.

### PUT <repository>/predicateMapping

Takes two arguments, `predicate` and `primitiveType`, and defines a predicate mapping on them.

### DELETE <repository>/predicateMapping

Deletes a type mapping. Takes one parameter, `predicate`, which should be an RDF resource.

### POST <repository>/eval

Only available when the server is started in non-safe mode. Evaluates the request body as Common Lisp code, with `*package*` set the current environment's package. Takes an optional `environment` argument.

### GET <repository>/geo/types

Retrieve a list of geospatial types defined in the store.

### PUT <repository>/geo/types/cartesian

Define a new Cartesian geospatial type. Returns the type URI.

stripWidth
  A floating-point number that determines the granularity of the type.
xmin, xmax, ymin, ymax
  Floating-point numbers that determine the size of the Cartesian plane that is modeled by this type.

### PUT <repository>/geo/types/spherical

Add a spherical geospatial type. Returns the type URI.

stripWidth
  A floating-point number that determines the granularity of the type.
unit
  Can be `degree` , `radian` , `km` , or `mile` . Determines the unit in which the `stripWidth` argument is given. Defaults to `degree` .
latmin, longmin, latmax, longmax
  Optional. Can be used to limit the size of the region modeled by this type. Default is to span the whole sphere.

### GET <repository>/geo/box

Fetch all triples with a given predicate whose object is a geospatial value inside the given box.

type
  The geospatial subtype of the object field.
predicate
  The predicate to look for.
xmin, ymin, xmax, ymax
  The bounding box.
limit
  Optional. Used to limit the amount of returned triples.

### GET <repository>/geo/circle

Retrieve triples within a circle. `type`, `predicate`, and `limit` argument as with /geo/box. Takes `x`, `y`, and `radius` arguments, all floating-point numbers, to specify the circle.

### PUT <repository>/geo/polygon

Create a polygon in the store. Takes a parameter `resource`, which sets the name under which the polygon should be stored, and three or more `point` arguments, which must be geospatial literals that represent the points of the polygon.

### GET <repository>/geo/polygon

Retrieve triples whose object lies inside a polygon. `type`, `predicate`, and `limit` work as with /geo/box. The `polygon` parameter must hold the name of a polygon stored with the above PUT service.

### GET <repository>/geo/haversine

Retrieve triples whose object lies within a circle in a spherical system. Takes `type`, `predicate`, and `limit` arguments like /geo/box, `lat` and `long` arguments to specify the center of the circle, and a `radius` argument, which defaults to an amount of kilometers, but which can be set to miles by passing a `unit` parameter with the value `mile`.

### GET <repository>/tripleCache

Find out whether the 'spogi cache' is enabled, and what size it has. Returns an integer — 0 when the cache is disabled, the size of the cache otherwise.

### PUT <repository>/tripleCache

Enable the `spogi` cache in this repository. Takes an optional `size` argument to explicitly specify the size of the cache.

### DELETE <repository>/tripleCache

Disable the `spogi` cache for this repository.

### GET <catalog>/AGVersion

Returns the version AllegroGraph running on the server, as a string. For example `3.0.1`.

## RDF-Transaction data format

The `application/x-rdftransaction` mime type, as accepted by the /statements service, is not standardised or even widely documented, so we quickly describe it here. The format originates from the Sesame HTTP protocol.

Documents of this type are XML documents containing a number of triple additions and removals, along with namespace definitions and removals. They are conceptually executed as a transaction - either completely, or not at all — but because the 3.x versions of AllegroGraph have no support for real transactions yet, there are some error situations in which this does not hold.

An RDF transaction document looks roughly like this:

    <transaction>
      <add>
        <bnode>person4</bnode>
        <uri>http://www.w3.org/1999/02/22-rdf-syntax-ns#type</uri>
        <uri>http://www.franz.com/simple#person</uri>
      </add>
      <add>
        <bnode>person4</bnode>
        <uri>http://www.franz.com/simple#birth</uri>
        <literal datatype="http://www.w3.org/2001/XMLSchema#date">1917-05-29</literal>
      </add>
      <remove>
        <null/>
        <uri>http://www.franz.com/simple#first-name</uri>
        <null/>
      </remove>
      <addNamespace prefix="http://www.franz.com/simple#" name="fr"/>
      <clear>
        <uri>http://franz.com/simple#context1</uri>
      </clear>
    </transaction>

A transaction's top-level tag is always `transaction`. Inside of this, any amount of actions are specified, which are executed in the order in which they are given.

The `add` action adds a triple. It should contain three nodes, that indicate the subject, predicate, and object of the triple, and may contain a fourth node to give the triple a context.

These child nodes can be either an `uri` tag containing a resource's URI, a `bnode` tag containing an ID that is used to be able to refer to the same blank node multiple times in the document, or a `literal` tag, that contains a string. `literal` tags may have `datatype` or `xml:lang` attributes to assign them a type or a language.

The `remove` action contains up to three child nodes, specifying the subject, predicate, and object of the triples to remove. Any of these can be given as a `null` tag (or left out altogether) to count as a wildcard. `removeFromNamedContext` works the same, but can have up to four child nodes, with the fourth one specifying the context of the triples to remove. If this is given as `null` it does not count as a wildcard, but refers to the default context of the store.

`clear` also removes triples (you notice some duplication here), but has only one (optional) child node, which works like the fourth argument to `removeFromNamedContext` — it specifies the context to clear, with `null` meaning the default context.

Finally, there are `setNamespace` and `removeNamespace` tags, which don't allow child nodes. The first should have a `prefix` and `name` attribute, which specify the URI and name of the namespace, and the second only a `prefix` argument. Note that these documents can't actually use namespaces, only define and remove them. To control the environment in which namespaces are added, pass an `environment` parameter to /statements.

## Common Lisp Programming interface

The symbols mentioned here live in the `db.agraph.http.server` module.

    create-server (&key port url wserver-args username password
                        unsafe-prolog allow-eval allow-remote)
    → agraph-http-server

This creates, starts, and returns a server. `port` specifies the port on which to run, and defaults to 80. `url` can be used to determine under which URL the catalogs (and subsequently everything else) can be found. It defaults to `"/catalogs"`. To pass additional options to the HTTP server (AllegroServe), a list of arguments can be given as the `wserver-args` parameter -- these will be passed to `net.aserve:start`.

`username` and `password` arguments can be passed to this function to protect the server using basic HTTP authentication. When `unsafe-prolog` is true, the server will allow arbitrary Lisp code in Prolog queries. Setting `allow-eval` to true enables the /eval service. `allow-remote`, which defaults to false, determines whether remote stores can be opened in this server.

    shutdown-server (server)

Shut down a server. This will stop the web server, and close all triple stores that the server has open.

    add-catalog (server directory)

Publish a catalog in the given server. `directory` should be a file system path pointing at the directory where the stores for this catalog can be found.