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 <-- or <- 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.

Copyright (c) 2005 - 2011 Franz, Incorporated

Last updated 18 March 2011 at 11:45