REST API

Note: This API is ALPHA and subject to change as we get feedback from early users.

The REST Service

A Datomic peer can be run as a standalone HTTP service using the bin/rest command:

bin/rest -p port [-o origins]? [alias uri]+

The URIs are as described in the documentation for connect with the database name elided, for example:

datomic:ddb://aws-region/ddb-table?aws_access_key_id=XXX&aws_secret_key=YYY

Clients of the REST API will use the supplied storage aliases to talk about the storages, and will be unaware of the connection and location details. A storage alias is set with the [alias uri] form above, e.g.:

dev datomic:dev://localhost:4334/

Would alias the local dev storage as "dev" and make it accessible through REST.

The origins are a comma-delimited list of allowed origins for Cross-Origin Resource Sharing (CORS) requests. Use /'*'/ to allow requests from all origins.

A fully formed launch command for the REST service with the localhost's dev storage available through the alias dev would be:

bin/rest -p 8001 dev datomic:dev://localhost:4334/

You could then connect to the resulting Datomic REST Service at http://localhost:8001 and use the storage alias "dev" when required. The examples below use this service with the mbrainz 1968-1973 sample database restored.

Accessing the service

The REST service can be accessed from a browser or programmatically from a client program.

When accessed from the browser, the service is self-describing and interactive. To access it, simply navigate to the server and port where you started the service, for instance `http://localhost:8080/` and use the links in the HTML pages to explore the API. The pages contain forms that allow you to invoke all API operations.

For programmatic access, use your preferred HTTP client library to build and submit requests. For POST operations, you can send request bodies in either application/edn or application/x-www-form-urlencoded format. The service returns data in application/edn format by default. You can also use the Accept header to specify a desired response format, either application/edn or text/html (the 'Subscribe to events' operation is an exception to this rule, see below).

Exploring the API in the browser and translating interactions to EDN-based client code is a relatively straightforward process. Specific examples are provided in the section below. Note that query parameters must be URL encoded, if required.

API operations

This section lists the API operations exposed by the service, including the required URL format and parameters.

List aliases

Returns vector of storage aliases the REST service was configured with.

  • GET /data/
curl http://localhost:8001/data/

["dev"]

List databases

Returns vector of names of databases that exist in the specified storage.

  • GET /data/<storage-alias>/
    • storage-alias - One of the aliases configured when the REST service was started.
curl http://localhost:8001/data/dev/

["mbrainz-1968-1973"]

Create database

Creates a database in the specified storage, if it does not already exist.

  • POST /data/<storage-alias>/
    • storage-alias - One of the aliases configured when the REST service was started.
    • Request body
    • db-name - The name of the database to create.
application/edn{:db-name "new-db-name"}
application/x-www-form-urlencodeddb-name=new-db-name


curl -X POST -H "Content-Type: application/edn" http://localhost:8001/data/dev/ -d "{:db-name scratch}"

["mbrainz-1968-1973" "scratch"]

Transact

Executes a transaction against the specified database, returns result.

  • POST /data/<storage-alias>/<db-name>/
    • storage-alias - One of the aliases configured when the REST service was started.
    • db-name - Name of database in storage.
    • Request body
    • tx-data - The transaction to execute
application/edn{:tx-data [{:db/id #db/id[:db.part/user] …}]
application/x-www-form-urlencodedtx-data=[{:db/id #db/id[:db.part/user] …}]


curl -X POST -H "Content-Type: application/edn" http://localhost:8001/data/dev/scratch/ -d "{:tx-data [{:db/id #db/id[:db.part/user] :db/doc \"hello REST world\"}]}"

{:db-before {:basis-t 63, :db/alias "dev/scratch"}, :db-after {:basis-t 1000, :db/alias "dev/scratch"},
:tx-data [{:e 13194139534312, :a 50, :v #inst "2014-12-01T15:27:26.632-00:00", :tx 13194139534312, :added true}
{:e 17592186045417, :a 62, :v "hello REST world", :tx 13194139534312, :added true}],
:tempids {-9223350046623220292 17592186045417}}

Retrieve database info

Returns information about specified database.

  • GET /data/<storage-alias>/<db-name>/<basis-t>/
    • storage-alias - One of the aliases configured when the REST service was started.
    • db-name - Name of database in storage.
    • basis-t - A t value or `-` for current database value.
curl http://localhost:8001/data/dev/mbrainz-1968-1973/-/

{:db/alias "dev/mbrainz-1968-1973", :basis-t 130627}

Datoms

Returns a set or range of datoms from an index.

  • GET /data/<storage-alias>/<db-name>/<basis-t>/datoms?index=<index>[&e=<e>][&a=<a>][&v=<v>][&start=<start>][&end=<end>][&offset=<offset>][&limit=<limit>][&as-of=<as-of-t>][&since=<since-t>][&history=<history>]
    • storage-alias - One of the aliases configured when the REST service was started.
    • db-name - Name of database in storage.
    • basis-t - A t value or `-` for current database value.
    • index - The index to use, one of aevt, eavt, avet or vaet; one or more leading components of the index can be supplied using e, a and v
    • e - An entity id or ident (optional)
    • a - An attribute id or ident (optional)
    • v - A specific value (optional)
    • start - A starting value for an index range (optional)
    • end - An ending value for an index range (optional)
    • limit - Number of results to return (optional)
    • offset - First result to return (optional)
    • as-of-t - A t value that filters the database to only include facts asserted as of that time (optional)
    • since-t - A t value that filters the database to only include facts asserted since that time (optional)
    • history - Boolean indicating whether to use a database value containing all historical facts (optional)
curl http://localhost:8001/data/dev/mbrainz-1968-1973/-/datoms\?index\=avet\&e\=\&a\=\&v\=\&start\=\&end\=\&offset\=\&limit\=100\&as-
of\=\&since\=

[
 {:e 91, :a 10, :v :abstractRelease/artistCredit, :tx 13194139534313, :added true}
 {:e 64, :a 10, :v :abstractRelease/artists, :tx 1319 4139534312, :added true}
 {:e 78, :a 10, :v :abstractRelease/gid, :tx 13194139534312, :added true}
 {:e 92, :a 10, :v :abstractRelease/name, :tx 13194139534313, :added true}
 ...
]

Entity

Returns all attributes of specified entity.

  • GET /data/<storage-alias/<db-name>/<basis-t>/entity?e=<e>[&as-of=<as-of-t>][&since=<since-t>]
    • storage-alias - One of the aliases configured when the REST service was started.
    • db-name - Name of database in storage.
    • basis-t - A t value or `-` for current database value.
    • e - An entity id or ident
    • as-of-t - A t value that filters the database to only include facts asserted as of that time (optional)
    • since-t - A t value that filters the database to only include facts asserted since that time (optional)
curl http://localhost:8001/data/dev/mbrainz-1968-1973/-/entity\?e\=17592186048482\&as-of\=\&since\=

{:artist/startMonth 2,
:artist/type :artist.type/group,
:artist/startYear 1964,
:artist/sortName "Who, The",
:artist/name "The Who",
:artist/gid #uuid "9fdaa16b-a6c4-4831-b87c-bc9ca8ce7eaa",
:artist/country :country/GB,
:db/id 17592186048482}

Query

Executes a query against one or more databases, returns results.

  • GET /api/query?q=<query>&args=<args>[&limit=<limit>][&offset=<offset>]
    • query - Query expression
    • args - Vector of arguments to query, must include database alias
    • limit - Number of results to return (optional)
    • offset - First result to return (optional)
  • POST /api/query
    • Request body
    • Same arguments as GET, supports longer list of args
application/edn{:q [:find …] :args [{:db/alias … }]}
application/x-www-form-urlencodedq=[:find …]&args=[{:db/alias …}]


curl http://localhost:8001/api/query?q=%5B%3Afind+%3Fe+%3Ain+%24+%3Fname+%3Awhere+%5B%3Fe+%3Aartist%2Fname+%3Fname%5D%5D&args=%5B%7B%3Adb%2Falias+%22dev%2Fmbrainz-1968-1973%22%7D+%22The+Who%22%5D&offset=&limit=

[[17592186048482]]

Subscribe to events

Starts a Server-Sent Events (SSE) stream to deliver transaction reports to a client.

  • GET /data/<storage-alias>/<db-name>/<basis-t>/events (browser access)
    • storage-alias - One of the aliases configured when the REST service was started.
    • db-name - Name of database in storage.
    • basis-t - A t value or `-` for current database value.
http://localhost:8001/data/dev/mbrainz-1968-1973/-/events
  • GET /events/<storage-alias/<db-name> (programmatic access)
    • storage-alias - One of the aliases configured when the REST service was started.
    • db-name - Name of database in storage.
    • Client must send 'Accept: text/event-stream' header in GET request, as per the SSE spec. A successful connection returns 200 and leaves the connection open, transmitting heartbeat comment lines and transaction reports.
curl -H "Accept: text/event-stream" http://localhost:8001/events/dev/mbrainz-1968-1973