Table of Contents

Overview

Conventions

Example session

URL summary

Global URLs

User management

Catalog interface

Federation

Repository interface

Namespaces

Type mappings

Geo-spatial queries

Social network analysis

Sessions

Process management

Communication between an AllegroGraph server and other processes happens through HTTP. This document describes the HTTP entry points the server provides, and how to use them. Most people will prefer to use a client library written in their language of choice to communicate with the server, but when no such library exists, or there is a reason not to use one, working directly with HTTP is an option.

The protocol described here is compatible (is a super-set of) with the Sesame 2.0 HTTP protocol and the W3C SPARQL protocol.

Overview

An AllegroGraph server exposes one or more catalogs, each containing any number of repositories (triple stores). The catalog layout of a server, as well as the port on which it listens for HTTP connections, is defined through its configuration file.

When the server is running, for example on the default port 10035, a catalog named public would be available under http://localhost:10035/catalogs/public, whereas the root catalog lives at http://localhost:10035/. Opening such URLs in a browser will present you with WebView, a web-interface to the catalogs. To manipulate or inspect the repositories directly, more specific URLs have to be constructed. For example, requesting this on tells you how many statements (triples) there are in the repository people in the root catalog: 

http://localhost:10035/repositories/people/size

Conventions

The AllegroGraph server tries to make effective use of HTTP features such as content-negotiation, status codes, and request methods. As such, a good understanding of the ideas behind HTTP will help when working with this protocol.

Input conventions

Unless noted otherwise, the services that take parameters expect these to be appended to the URL as a query string — as in ?name=John%20Doe. For POST requests that send along a Content-Type header of application/x-www-form-urlencoded, the query string can also be put in the request body. Any 'dynamic' part of a URL (for example the repository name) should also be URL-encoded — specifically, slashes should be encoded as %2F.

When making a PUT or POST request that includes a body, it is usually required to specify a meaningful Content-Type for this body.

When RDF terms have to be passed as parameters, or included in JSON-encoded data, these are written in a format resembling N-triples, with the caveat that non-ASCII characters 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.

All non-ASCII input to the server should be encoded using UTF-8. When such characters end up a URL, the individual bytes of their UTF-8 representation should be taken and escaped as normal (%HH).

If there is the need to send data to the server in compressed form, a Content-Encoding header can be provided along with an encoded request body. The server understands deflate and gzip encoding on all platforms, and bzip2 on platforms that provide the bzcat utility (most Unixes).

When making a request without an Authorization header, the request is treated as coming from user anonymous (if such a user exists). Basic HTTP authentication must be used to identify oneself as another user.

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. When no Accept, or an Accept of */* is specified, the server prefers text/plain, in order to make it easy to explore the interface from a web browser.

Almost every service is capable of returning text/plain (just text) and application/json (JSON-encoded) responses. Services returning sets of triples can return the following:

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. The application/x-quints+json format works like the JSON triple format, but adds an extra field, the triple ID, to the front of every triple.

Services returning lists or sets of results (SPARQL select queries, for example) support the application/sparql-results+xml (see here) and application/sparql-results+json (see here) format. When encoded as regular JSON (application/json), such results take the form of an object with two properties. names contains an array of column labels, and values an array of arrays of values — the result rows. Again, text/integer will cause only the number of results to be returned.

When asked to (using the Accept-Encoding header), the server will compress the response body using 'gzip' or 'deflate'. For typical RDF data, this will make the response a lot smaller.

Error responses

Error responses will choose the appropriate HTTP status code as much as possible. Since there are a lot of circumstances that result in 400 Bad Request, those are (usually) tagged with an additional error code. This code will be a capitalized string at the start of the body, followed by a colon, a space, and then a more detailed description of the problem.

The above paragraph says 'usually', since in the case of really malformed requests, the HTTP server implementation underlying the AllegroGraph server can also return a 400 response, which won't include such an error code. Thus, clients shouldn't recklessly assume the code is present, but could, for example, match against the regular expression /^([A-Z ]): (.*)$/ to separate the code from the message.

Error codes will be one of the following:

INVALID PARAMETERS
The set of parameters passed to the request, or the value of one of them, is not valid for this service.
MALFORMED QUERY
An unsyntactic query was given.
MALFORMED DATA
The request contains unsyntactic data.
MALFORMED PROGRAM
A Lisp program included in the request could not be executed.
UNSUPPORTED QUERY LANGUAGE
A query language was specified that is not understood by this server.
UNSUPPORTED FILE FORMAT
Data was provided in a format that the server does not understand.
INAPPROPRIATE REQUEST
The request expresses something wrong-headed, like writing to a federated store.
PRECONDITION FAILED
A necessary precondition for executing the request does not hold.
NOT IMPLEMENTED
The request tries to use functionality that is not implemented.
COMMIT FAILED
A transaction-conflict between the request and other, concurrent transactions arose. This can only happen when changing a repository's meta-data (things like type mappings).

Example session

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

First, to create a repository named test, we'd issue the following request: 

PUT /repositories/test HTTP/1.1  
Accept: */*

To which the server responds: 

HTTP/1.1 204 No Content

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

HTTP/1.1 400 Bad Request  
Content-Type: text/plain; charset=UTF-8  
 
PRECONDITION FAILED: There is already a repository 'test'.

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

GET /repositories HTTP/1.1  
Accept: application/json  
 
HTTP/1.1 200 OK  
Content-Type: application/json; charset=UTF-8  
 
[{"uri": "<http://localhost:10035/repositories/test>",  
  "id": "\"test\"",  
  "title": "\"test\"",  
  "readable": true  
  "writeable": true}]

Next, let's add a few statements to this store... 

POST /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 /repositories/test/statements HTTP/1.1  
Accept: */*  
Content-Type: text/plain  
 
<http://example.org#alice> <http://example.org#age> "26" .  
<http://example.org#bob> <http://example.org#age> "33" .

To find out Alice's name and age, we could issue the following SPARQL query: 

select ?n ?age {  
  <http://example.org#alice> <http://example.org#name> ?n ;  
                             <http://example.org#age ?age  
}

In the following request, [QUERY] is the URL-encoded equivalent of this query: 

GET /repositories/test?query=[QUERY] HTTP/1.1  
Accept: application/json  
 
HTTP/1.1 200 OK  
Content-Type: application/json; charset=UTF-8  
 
{"names":["n", "age"], "values":[["\"alice\"", "\"26\""]]}

Or, asking for SPARQL XML results: 

GET /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"/><variable name="age"/></head>  
  <results>  
    <result>  
      <binding name="n"><literal>alice</literal></binding>  
      <binding name="age"><literal>26</literal></binding>  
    </result>  
  </results>  
</sparql>

To fetch all statements in a repository, issue a request like this: 

GET /repositories/test/statements  
Accept: text/plain  
 
HTTP/1.1 200 OK  
Content-Type text/plain  
 
<http://example.org#alice> <http://example.org#name> "Alice" .  
<http://example.org#bob> <http://example.org#name> "Bob" .  
<http://example.org#alice> <http://example.org#age> "26" .  
<http://example.org#bob> <http://example.org#age> "33" .

URL summary

The following overview gives a quick, if minimal, summary of the URLs exposed by the server, and the methods allowed on them. Each method links to a description of the functionality exposed.

Under a catalog prefix (/ for the root catalog, /catalogs/[name]/ for named catalogs), the following services are available:

Global URLs

GET /catalogs

Returns a set of catalogs that are available on this server, and accessible to the user. For each catalog, id and uri properties are returned.

PUT /catalogs/[name]

If dynamic catalogs are enabled for the server (see the DynamicCatalogs directive), this can be used to create a new catalog. Takes two parameters, expectedStoreSize (an integer) and sharedMemSize (a size, like 120m), which determine the default settings for the catalog - see the configuration file documentation for their meaning.

DELETE /catalogs/[name]

Deletes a catalog. Only dynamic catalogs (those created through HTTP) can be deleted in this way.

GET /version

Returns the version of the AllegroGraph server, as a string. For example 4.0.

GET /version/date

Return the date on which the server was built.

GET /version/revision

Return the git hash of the revision that the server was built from.

POST /reconfigure

Posting to this URL will cause the server to re-read its configuration file, and update itself to reflect the new configuration.

POST /reopenLog (@post-reopenlog)

Causes the server to re-open its log file. This is useful for log rotation.

GET /initfile

An initialization-file can be specified for a server, which is a collection of Common Lisp code that is executed in every shared back-end (see below) as it is created. This retrieves that file.

PUT /initfile

Replace the current initialization file with the body of the request. Takes one boolean parameter, restart, which defaults to true, and specifies whether any running shared back-ends should be shut down, so that subsequent requests will be handled by back-ends that include the new code.

DELETE /initfile

Remove the server's initialization file.

User management

The AllegroGraph server uses a simple access-control scheme. Requests made with a valid Authorization header get assigned to the authorized user. Each user has a set of permissions, which are used to determine whether the request can be made.

The user named anonymous plays a special role. When such a user exists, any request made without authentication information is assigned to that user. By default, no anonymous user is defined, which disallows anonymous access.

The following permissions flags are defined:

super
This flag makes one a superuser, which means one can manage user accounts. Having the super permission automatically grants all other permissions.
eval
This controls whether a user is allowed to use the 'eval-in-server' entry point, and use arbitrary Lisp code in their Prolog queries. This makes it possible to write more powerful queries, and move work to the server to improve efficiency. Note, however, that this also allows all manner of privilege escalation, and should only be granted to trusted users.
session
Controls whether a user can open their own sessions.

On top of that, read and write access can be specified per catalog and per store (as well as globally). read access allows one to query a repository, with write access one can also modify it. At the catalog level, write access permits the deleting and creating of repositories.

Each user can be assigned to a set of roles, each of which can also be granted permissions. The effective set of permissions that a user has is the union of their own permissions and those of their roles.

Most of the user-management services are only available to super-users. A normal user is allowed to inspect its own permissions, manage its user-data, and delete its own account.

GET /users

Returns a list of names of all the users that have been defined. For example: 

GET /users HTTP/1.1  
Accept: application/json  
 
HTTP/1.1 200 OK  
Content-Type: application/json; charset=UTF-8  
 
["anonymous", "marijnh", "testuser"]

PUT /users/[name]

Create a new user. Expects a password parameter, which specifies the user's password (can be left off when creating the anonymous user).

DELETE /users/[name]

Delete a user.

POST /users/[name]/password

Change the password for the given user. The new password should be in the body of the request.

GET /users/[name]/roles

Retrieves a list of names, indicating the roles this user has.

PUT /users/[name]/roles/[role]

Add a role to a user.

DELETE /users/[name]/roles/[role]

Remove a role from a user. For example: 

DELETE /users/anonymous/roles/project_a HTTP/1.1

GET /users/[name]/permissions

List the permission flags that have been assigned to a user (any of super, eval, session). This is what a request fetching permission flags as plain text looks like: 

GET /users/marijnh/permissions  
Accept: text/plain  
 
HTTP/1.1 200 OK  
Content-Type: text/plain; charset=UTF-8  
 
eval  
session

GET /users/[name]/effectivePermissions

Retrieve the permission flags assigned to the user, or any of its roles.

PUT /user/[name]/permissions/[type]

Assigns the given permission to this user. type should be super, eval, or session.

DELETE /user/[name]/permissions/[type]

Revokes the given permission for this user.

GET /users/[name]/access

Retrieve the read/write access for a user. This returns a result set, each element of which has a read, write, catalog, and repository component. The first two are booleans, the latter two strings. For permissions granted globally, catalog and repository will have a value of "*", for those granted per-catalog, only repository will be "*". catalog normally contains the catalog name, but for the root catalog "/" is used, and to refer to the federation pseudo-catalog, "/federated" is used.

For example, read access to all repositories in the public catalog is specified (in JSON format) by: 

{read: true, write: false, catalog: "public, repository: "*"}

Whereas read/write access to repository scratch in the root catalog would be: 

{read: true, write: true, catalog: "/", repository: "scratch"}

GET /users/[name]/effectiveAccess

As above, but also includes the access granted to roles that this user has.

PUT /users/[name]/access

This is used to grant read/write access to a user. It takes four parameters:

read
Whether to grant read access. A boolean, defaults to false.
write
Whether to grant write access. Boolean, defaults to false.
catalog
Which catalog to grant the access on. Leave off or pass * to grant access on all catalogs. Again, use / for the root catalog, /federated for the federation pseudo-catalog.
repository
Specifies the repository that access is granted on. Passing *, or leaving the parameter off, means all repositories in the given catalog.

This request grants the user testuser read access to all repositories in the root catalog: 

PUT /users/testuser/access?read=true&catalog=%2f HTTP/1.1

DELETE /users/[name]/access

Takes the same parameters as PUT on this URL, but revokes the access instead of granting it.

GET /users/[name]/data

Each user has a simple key-value store associated with it. This is mostly used by WebView to save some settings, but can be useful in other applications.

This service returns a result set containing id and uri fields, listing the keys stored for this user, and the URL under which their data can be found (see below).

GET /users/[name]/data/[key]

Fetches the user-data under key. Returns a string.

PUT /users/[name]/data/[key]

Stores data in a user's key-value store. The request body should contain the data to store.

DELETE /users/[name]/data/[key]

Deletes data from a user's key-value store.

GET /roles

Returns the names of all roles that have been defined.

PUT /roles/[role]

Creates a new role.

DELETE /roles/[role]

Deletes a role. Any users that have been assigned this role will lose it.

GET /roles/[role]/permissions

Lists the permission flags granted to a role.

PUT /roles/[role]/permissions/[type]

Grant a role a certain permission. type should be super, eval, or session.

DELETE /roles/[role]/permissions/[type]

Revoke a permission for a role.

GET /roles/[role]/access

Query the access granted to a role. Returns a result in the same format as the equivalent service for users.

PUT /roles/[role]/access

Grant read/write access to a role. See here for the parameters that are expected.

DELETE /roles/[role]/access

Revoke read/write access for a role. Accepts the same parameters as above.

Catalog interface

GET /protocol

Returns the protocol version of the Sesame interface, as an integer. The protocol described in this document is 4.

GET /repositories

Lists the repositories in this catalog that are accessible to the user. The result is a set of tuples containing id (the name of the repository) and uri (a link to the repository) fields. For compatibility with Sesame, there are also fields readable, writable, and title, but these do not contain interesting information. Stores are always readable and writeable (provided your user has the permissions), and title is the same as the id. 

GET /repositories HTTP/1.1  
Accept: application/json  
 
HTTP/1.1 200 OK  
Content-Type: application/json; charset=UTF-8  
 
[{"uri":"http://localhost:10035/repositories/store1",  
  "id":"store1",  
  "title":"store1",  
  "readable":true,  
  "writable":true},  
 ... other stores ...]

Or, when fetching the list of repositories in a non-root catalog: 

GET /catalogs/people/repositories HTTP/1.1

PUT /repositories/[name]

Creates a new, empty repository. Supports two configuration arguments: expectedSize, an integer, to configure the expected size of the repository, and deleteDuplicates, a boolean, to configure whether duplicate triples will be deleted during merging.

When a repository with the given name already exists, it is overwritten, unless a parameter override with value false is passed.

DELETE /repositories/[name]

Delete a repository. Might fail if someone else is accessing the repository.

Federation

Federation is used to approach several repositories as if they were a single repository — allowing queries on the union of their statements. Such federated repositories can not be written to.

Under a federation url (/federated/[name]), the regular repository interface is available. For example, /federated/people/statements can be used to query the statements in the federated repository named people.

GET /federated

Lists the federated stores present on the server (that your user has access to). It uses the same return format as /repositories, except that here the writable flag will be false.

PUT /federated/[name]

Create a new federated repository. Takes any number of url and repo parameters, which specify the repositories to be federated. repo should have the form catalog:repository, or plain repository for a repository in the root catalog. To federate off-server repositories, pass their URL, including user credentials if necessary. For example http://user:[email protected]:10035/repositories/people.

If a federation by this name already exists, it is replaced, unless an override parameter with value false is passed.

DELETE /federated/[name]

Delete a federation. Does not affect the federated stores in any way.

Repository interface

GET/POST /repositories/[name]

(Note that if no query parameter is given, this will return the WebView HTML page instead of the service described here.)

This URL is used to run queries against a repository. It conforms to both the Sesame and SPARQL protocol interfaces — this is why some of the parameter names may look inconsistent.

SPARQL/Update queries are allowed, but only when the request is made using POST instead of GET (and the user has write access to the repository).

This service takes the following parameters:

query
The query to be executed. The query may use the namespace prefixes defined for the user.
queryLn
The language of the query. Can be sparql or prolog. Defaults to sparql.
infer
A string that determines what kind of reasoning is used when executing the query. Default is false, no reasoning. Other options are rdfs++ (same as true), and hasvalue.
context
Can be passed zero or more times. Sets the graph name, or list of graph names, that will be used by this query (as in FROM). 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 (as in FROM NAMED).
default-graph-uri
Can be passed any number of times. Works like context except that plain-URI values should be given, without wrapping < and > characters.
named-graph-uri
Works like default-graph-uri, except that this specifies the named graphs to be used.
limit
An integer. Can be used to limit the amount of results returned by the query.
offset
An integer. Can be used to skip a number of results at the start of the query.
$[varname]
Parameters starting with a $ character can be used to bind query variables to fixed value (an N-Triples term) when executing a SPARQL 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.
defaultGraphName
Can be used to provide a resource (URL) name for the default graph. Any references to that resource will reference the default graph, and in the output the resource will be substituted for any references to the default graph. Can be given multiple times to have multiple names refer to this graph, but only the first one will appear in the output.
planner
Can be used to control the way the query is planned .

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

Prolog queries are allowed to return nested lists of results, in which case the result can only be returned as application/json, and the nested structure (both in the list of column names and in the results themselves) will be represented as nested JSON arrays.

GET /repositories/[name]/size

Returns the amount of statements 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 /repositories/[name]/statements

Retrieves statements (triples) by matching against their components. All parameters are optional — when none are given, every statement 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 one of these resources'.
subjEnd
Can only be given if exactly one subj parameter is given. Matches a range of subjects.
pred
Match a specific predicate. Can be passed multiple times, like subj, to match a set.
predEnd
Perform a range query on the predicate.
obj
Match a specific object. Pass multiple values to match a set.
objEnd
Range query on objects.
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.
contextEnd
Range query on contexts / graph names.
limit
An integer indicating the maximum amount of results to return.
offset
An integer. Tell the server to skip a number of results before it starts returning.
infer
Used to turn on reasoning for this query. Valid values are false, rdfs++, and hasvalue. Default is false — no reasoning.

DELETE /repositories/[name]/statements

Deletes statements matching the given parameters. When no parameters are given, every triple in the store is deleted. Returns the number of triples 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.

This deletes all statements in the graph named "A" (of which there are 25). 

DELETE /repositories/repo1/statements?context=%22A%22 HTTP/1.1  
Accept: application/json  
 
HTTP/1.1 200 OK  
Content-Type: application/json; charset=UTF-8  
 
25

PUT/POST /repositories/[name]/statements

Add statements to a store. When the PUT method is used, the store is emptied first, whereas the POST method just adds triples. The value returned is an integer indicating the amount of triples loaded.

The Content-Type header determines the way the given data is interpreted. The following formats are supported:

Normally, the body of the request is used as input data. One can pass a file parameter to indicate a (server-side) file-name to be loaded, or a url parameter to load a file directly off the web. Other supported parameters are:

baseURI
When loading RDF/XML data, the value of this parameter is used as the base URI of the document.
context
Used to set the named graph into which the new data is stored. (Ignored for formats like N-quads, which store their own graph identifiers.)
commit
A positive integer. Will cause a commit to happen after every N added statements. Can be used to work around the fact that importing a huge amount of statements in a single transaction will require a lot of memory.

This request, where [URL] is the encoded form of some URL that contains an N-triples file, loads the triples from that URL into the scratch store under context "B". 

POST /repositories/scratch/statements?url=[URL]&context=%22B%22 HTTP/1.1  
Accept: application/json  
 
HTTP/1.1 200 OK  
Content-Type: application/json; charset=UTF-8  
 
2530

RDF-Transaction data format

The application/x-rdftransaction mime type, as accepted by the /statements service, is not standardized 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. They are executed as a transaction - either completely, or not at all. (Though note that this does not mean an implicit commit is executed on dedicated back-ends.)

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>  
  <clear>  
    <uri>http://franz.com/simple#context1</uri>  
  </clear>  
</transaction>

A transaction's root 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 wild-card. 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 wild-card, 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.

POST /repositories/[name]/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 /repositories/[name]/statements/id

Fetches a set of statements by ID. Takes any number of id parameters, and returns a set of triples.

GET /repositories/[name]/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 /catalogs/people/repositories/repo1/contexts 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="contextID"/></head>  
  <results>  
    <result>  
      <binding name="contextID">  
        <literal>A</literal>  
      </binding>  
    </result>  
  </results>  
</sparql>

POST /repositories/[name]/functor

Define Prolog functors, which can be used in Prolog queries. This is only allowed when accessing a dedicated back-end.

The body of the request should hold the definition for one or more Prolog functors, in Lisp syntax, using the &lt;-- or &lt;- operators.

POST /repositories/[name]/commit

Commit the current transaction. Only meaningful in dedicated back-ends.

POST /repositories/[name]/rollback

Roll back the current transaction (discard all changes made since last commit). Only meaningful in dedicated back-ends.

POST /repositories/[name]/eval

Evaluates the request body as Common Lisp code, with *package* set to the AllegroGraph user package. Makes an attempt to return the result in a sensible format, falling back to printing it (as per prin1) and returning it as a string.

GET/POST /repositories/[name]/freetext

Perform a query on the free-text indices of the store, if any. A list of matching triples is returned.

pattern
The text to search for. Either this or expression should be passed.
expression
An S-expression combining search strings using and and or. For example (and "coil" (or "snake" "serpent")).
predicate
Can be specified multiple times. When given, only triples whose predicate is given through this parameter are included in the result set.
limit
An integer limiting the amount of results that can be returned.
offset
An integer telling the server to skip the first few results.

GET /repositories/repo1/freetext?pattern=RDF HTTP/1.1 Accept: text/plain

HTTP/1.1 200 OK Content-Type: text/plain; charset=UTF-8

"AGraph RDF store". .... others ....

GET /repositories/[name]/freetext/predicates

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

POST /repositories/[name]/freetext/predicates

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

POST /repositories/[name]/blankNodes

Ask the server to allocate and return a set of blank nodes. Takes one argument, amount, which should be an integer.

These nodes can, in principle, be used to refer to nodes when using other services. Note, however, that a lot of the standards related to RDF give blank nodes a document-wide scope, which means that referring to blank nodes by name from, for example, a SPARQL query or N-Triples document is not possible. The nodes are interpreted as local to the document, and assigned to a new blank node. 

POST /repositories/repo1/blankNodes?amount=2 HTTP/1.1  
Accept: text/plain  
 
HTTP/1.1 200 OK  
Content-Type: text/plain; charset=UTF-8  
 
_:s1x49c10bbc  
_:s2x49c10bbc

GET /repositories/[name]/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 /repositories/[name]/tripleCache

Enable the spogi cache in this repository. Takes an optional size argument to set the size of the cache.

DELETE /repositories/[name]/tripleCache

Disable the spogi cache for this repository.

GET /repositories/[name]/deleteDuplicates

Returns a boolean indicating whether deleting duplicate triples/quads during merges is turned on.

PUT /repositories/[name]/deleteDuplicates

Turns deleting duplicates during merge on.

DELETE /repositories/[name]/deleteDuplicates

Disables deleting duplicates during merge.

Namespaces

In order to make queries shorter and more readable, a user can define namespaces, which will be used for queries issued by this user.

GET /repositories/[name]/namespaces

List the currently active namespaces for your user, as tuples with prefix and namespace (the URI) fields. For example: 

GET /catalogs/scratch/repositories/repo2/namespaces HTTP/1.1  
Accept: application/json  
 
HTTP/1.1 200 OK  
Content-Type: application/json; charset=UTF-8  
 
[{"prefix":"rdf","namespace":"http://www.w3.org/1999/02/22-rdf-syntax-ns#"},  
 {"prefix":"owl","namespace":"http://www.w3.org/2002/07/owl#"},  
 ... etc ...]

DELETE /repositories/[name]/namespaces

Deletes all namespaces in this repository for the current user. If a reset argument of true is passed, the user's namespaces are reset to the default set of namespaces.

GET /repositories/[name]/namespaces/[prefix]

Returns the namespace URI defined for the given prefix.

PUT/POST /repositories/[name]/namespaces/[prefix]

Create a new namespace. The body of the request should contain the URI for the namespace, as plain text, as in: 

POST /catalogs/scratch/repositories/repo2/namespaces/ex HTTP/1.1  
Content-Type: text/plain; charset=UTF-8  
 
http://www.example.com/

DELETE /repositories/[name]/namespaces/[prefix]

Delete a namespace.

Type mappings

AllegroGraph supports storing some types of literals in encoded, binary form. This typically makes them smaller (less disk usage), and makes it possible to run range queries against them.

Specifying which literals should be encoded can be done in two ways. There is 'datatype mapping', where a literal type is marked, and all literals of that type are encoded, and there is 'predicate mapping', where the objects in a statement with a given predicate are encoded.

When specifying a mapping, one has to choose an encoding to apply. To identify these encodings, we use XSD datatypes:

Typed literals of these types will be encoded by default. For other types, you have to specify your mapping before you import your data to have the encoding take place.

GET /repositories/[name]/mapping

Fetches a result set of currently specified mappings. Each row has a kind (datatype or predicate), part (the resource associated with the mapping), and encoding fields.

DELETE /repositories/[name]/mapping

Clear all non-automatic type mappings for this repository.

DELETE /repositories/[name]/mapping/all

Clear all type mappings for this repository including the automatic ones.

GET /repositories/[name]/mapping/type

Yields a list of literal types for which datatype mappings have been defined in this store. 

GET /repositories/test/mapping/type HTTP/1.1  
 
HTTP/1.1 200 OK  
Content-Type: text/plain; charset=UTF-8  
 
<http://www.example.com/myInteger>  
<http://www.w3.org/2001/XMLSchema#unsignedShort>  
<http://www.w3.org/2001/XMLSchema#dateTime>  
... etc ...

PUT/POST /repositories/[name]/mapping/type

Takes two arguments, type (the RDF literal type) and encoding, and defines a datatype mapping from the first to the second. For example, if [TYPE] is the URL-encoded form of <http://www.example.com/myInteger>, and [ENC] of <http://www.w3.org/2001/XMLSchema#int>, this request will cause myInteger literals to be encoded as integers: 

PUT /repositories/test/mapping/type?type=[TYPE]&encoding=[ENC] HTTP/1.1

DELETE /repositories/[name]/mapping/type

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

GET /repositories/[name]/mapping/predicate

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

PUT/POST /repositories/[name]/mapping/predicate

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

DELETE /repositories/[name]/mapping/predicate

Deletes a predicate mapping. Takes one parameter, predicate.

Geo-spatial queries

When literals are encoded as geo-spatial values, it is possible to efficiently perform geometric queries on them.

In order to do this, one defines a geo-spatial datatype, and then adds literals of that type to the store. AllegroGraph supports two kinds of geo-spatial datatypes, cartesian and spherical. A cartesian literal looks like this: 

"+10.0-17.5"^^<[cartesian type]>

Where the numbers are the X and Y coordinates of the point. A spherical literal uses ISO 6709 notation, for example: 

"+37.73+122.22"^^<[spherical type]>

GET /repositories/[name]/geo/types

Retrieve a list of geospatial types defined in the store.

POST /repositories/[name]/geo/types/cartesian

Define a new Cartesian geospatial type. Returns the type resource, which can be used as the type argument in the services below.

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 modelled by this type.

POST /repositories/[name]/geo/types/spherical

Add a spherical geospatial type. Returns the type resource.

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 modelled by this type. Default is to span the whole sphere.

For example, this defines a type with a granularity of 2 degrees: 

POST /repositories/repo1/geo/types/spherical?stripWidth=2 HTTP/1.1  
Accept: text/plain  
 
HTTP/1.1 200 OK  
Content-Type: text/plain; charset=UTF-8  
 
<http://franz.com/ns/allegrograph/3.0/geospatial/spherical/degrees/  
   -180.0/180.0/-90.0/90.0/2.0>

(The newline in the URI wouldn't be there in the actual response.)

GET /repositories/[name]/geo/box

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

type
The geospatial type 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.
infer
Optional argument to control whether triples inferred through reasoning should be included. Default is false (no reasoning), other accepted values are rdfs++ and hasvalue.

GET /repositories/[name]/geo/circle

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

GET /repositories/[name]/geo/haversine

Retrieve triples whose object lies within a circle in a spherical system. Takes type, predicate, infer, and limit arguments like /geo/box, lat and long arguments to specify the centre of the circle, and a radius argument. The unit used for radius defaults to kilometre, but can be set to mile by passing a unit parameter with the value mile.

PUT /repositories/[name]/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 /repositories/[name]/geo/polygon

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

Social network analysis

Some queries and operations are best expressed using graph-traversing generators . The following services make it possible to define such generators.

PUT /repositories/[name]/snaGenerators/[generator]

Creates a new generator under the given name. Accepts the following parameters:

objectOf
A predicate. Accepted multiple times. Causes the new generator to follow edges with the given predicate.
subjectOf
Like objectOf, but follow edges from object to subject.
undirected
Like the above, but follow edges in both directions.
query
A Prolog query, in which the variable ?node can be used to refer to the 'start' node, and whose results will be used as 'resulting' nodes. User namespaces may be used in this query.

PUT /repositories/[name]/neighborMatrices/[matrix]

Create a neighbor-matrix, which is a pre-computed generator.

group
A set of N-Triples terms (can be passed multiple times) which serve as start nodes for building up the matrix.
generator
The generator to use, by name.
depth
An integer specifying the maximum depth to which to compute the matrix. Defaults to 1.

Sessions

Normal requests will be handled by one of a set of shared back-end processes. (See server configuration.) The fact that they are shared between all incoming requests means there are certain limitations on the way they can be used — a shared back-end does not support transactions spanning multiple requests, and does not allow one to define new Prolog functors.

When transactions, functors, or other persistent state is needed, it is necessary to create a session. This spawns a process that you will have exclusive access to.

Requests to a session URL, unless the autoCommit parameter is given when starting the session, are handled inside a transaction. That means modifications to the store are not visible in other sessions or in shared back-ends until a commit request is made. A rollback request can be used to discard any changes made since the last commit.

Sessions time out after a certain period of idleness (can be set on creation), so an application that depends on a session being kept alive should periodically ping its session.

POST /repositories/[name]/session

Takes three parameters:

autoCommit
A boolean, which determines whether the session uses transactions (default is false, meaning transactions are enabled).
lifetime
An integer, specifying the amount of seconds the session can be idle before being collected.
loadInitFile
A boolean, defaulting to false, which determines whether the initfile is loaded into this session.

Returns the URL of the new session. Any sub-URLs that were valid under a repository's URL will also work under this session URL. For example, if http://localhost:55555 is returned, you can use http://localhost:55555/statements to retrieve the statements in the session.

POST [session-url]/session/close

Explicitly closes a session.

GET [session-url]/session/ping

Let the session know you still want to keep it alive. (Any other request to the session will have the same effect.)

GET [session-url]/session/autoCommit

Returns a boolean indicating whether auto-commit is currently active for this session.

POST [session-url]/session/autoCommit

Used to change the auto-commit flag for the session. Takes a single boolean argument, on.

Process management

An AllegroGraph server consists of a group of different operating-system processes. The following services provide a minimal process-debugging API over HTTP. All of them are only accessible to superusers.

GET /processes

Returns a list of process IDs showing the processes the server currently has running.

GET /processes/[id]

Returns stack traces for the threads in the given process.

DELETE /processes/[id]

Kills the specified process. Obviously, you yourself are responsible for any adverse effects this has on the functioning of the server.

POST /processes/[id]/telnet

Starts a telnet server in the specified process. A random port will be chosen for the server, which will be returned as the response. Note that the telnet server will allow anyone to connect, creating a something of a security concern if the server is on an open network.