HTTP

XTDB offers a REST API layer in the xtdb-http-server module that allows you to send transactions and run queries over HTTP.

Using XTDB in this manner is a valid use-case but it cannot support all of the features and benefits that running the XTDB node inside of your application provides, in particular the ability to efficiently combine custom code with multiple in-process Datalog queries.

Your application only needs to communicate with one XTDB node when using the REST API. Multiple XTDB nodes can placed be behind a HTTP load balancer to spread the writes and reads over a horizontally-scaled cluster transparently to the application. Each XTDB node in such a cluster will be independently catching up with the head of the transaction log, and since different queries might go to different nodes, you have to be slightly conscious of read consistency when designing your application to use XTDB in this way. Fortunately, you can readily achieve read-your-writes consistency with the ability to query consistent point-in-time snapshots using specific temporal coordinates.

The REST API also provides an experimental endpoint for SPARQL 1.1 Protocol queries under /_xtdb/sparql/, rewriting the query into the XTDB Datalog dialect. Only a small subset of SPARQL is supported and no other RDF features are available.

Starting an HTTP Server

Project Dependency

com.xtdb/xtdb-http-server {:mvn/version "{xtdb_version}"}

You can start up a Jetty HTTP/HTTP2 server on a node by including xtdb.http-server/server in your node configuration, optionally passing the server port:

JSON

{
  "xtdb.http-server/server": {
    "port": 3000,
    ...
  }
}

Clojure

{:xtdb.http-server/server {:port 3000
                           ...}

EDN

{:xtdb.http-server/server {:port 3000
                           ...}

Parameters

port (int, default 3000)
read-only? (boolean, default false): start the HTTP server in read-only mode
jwks (string): JSON Web Token (JWT) key set to authorise requests against - {"keys": […]}
jetty-opts (map): further options to pass to the Ring Jetty adapter

Ring Handler

XTDB also exposes a Ring handler that you can include within your own Ring-compatible server, with parameters as above:

(xtdb.http-server/->xtdb-handler xtdb-node {...})

Using a Remote API Client

In addition to calling the HTTP endpoints directly you can also use the remote API client, which implements the same interfaces/protocols as a local XTDB node, where possible.

Project Dependency

com.xtdb/xtdb-http-client {:mvn/version "{xtdb_version}"}

To connect to a pre-existing remote node, you need a URL to the node and the above on your classpath. We can then call xtdb.api/new-api-client, passing the URL. If the node was started on localhost:3000, you can connect to it by doing the following:

link:example$test/xtdb/docs/examples_test.clj[role=include]

Using the REST API

All of the REST endpoints return application/edn, application/json and application/transit+json. Individual endpoints may return additional types - see their docs below, or see the Swagger documentation here.

All endpoints with query-parameters accept them in both a kebab-case and camel cased format, (ie: if valid-time is taken, validTime will also be taken)

GET `/_xtdb/status`

Returns the current status information of the node.