REST API

The REST server is legacy and will no longer be supported for new development.

New projects should use the Client API.
The REST server will continue to ship with every release of Datomic, in order to support existing projects that use it.
Only critical bug fixes will be made to the REST server going forward.

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/
#+end_src example

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

Note that the trailing forward slash is required on the storage URI.

The /origins/ are a comma-delimited list of allowed origins for
Cross-Origin Resource Sharing ([[https://www.w3.org/TR/cors/][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: 

#+begin_src example
bin/rest -p 8001 dev datomic:dev://localhost:4334/

You could then connect to the resulting Datomic REST Service at https://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 https://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-urlencoded	db-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 "foo" …}]
application/x-www-form-urlencoded	tx-data=[{:db/id "foo" …}]

curl -X POST -H "Content-Type: application/edn" http://localhost:8001/data/dev/scratch/ -d "{:tx-data [{: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. Each database argument to query requires a map descriptor. Each descriptor must include a value for :db/alias. Fields allowed in the descriptor include:
  - :db/alias - Name of database in storage (required)
  - :basis-t - A t value or `-` for current database value (optional)
  - :as-of - A t value that filters the database to only include facts asserted as of that time (optional)
  - :since - 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)
- 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-urlencoded	q=[: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]]