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, e.g. datomic:mem:// or 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.

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

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 straightforward process. However, users have requested specific documentation on programmatic interaction with the service. It is 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 require URL format and parameters.

List aliases

  • Returns vector of storage aliases the REST service was configured with.
  • GET /data/

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.

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

Process transaction

  • 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] …}]

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.

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

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

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 …}]

Subscribe to events

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