If you PUT a JSON document with a Content-Type of application/vnd.oai.openapi+json;version=3.0.2, Site will treat this as an OpenAPI API definition, and serve that API for you. This OpenAPI API definition will contain the API endpoints, and provide schemas for the data transferred by the API. This tells the server how to validate data coming in to the API, and how to construct data on the way out.

APIs served from Site are good web citizens. They implement HTTP method semantics properly, with support for content negotiation, conditional requests, range requests and authentication.

APIs are also able to benefit from Site’s authorization module, Pass, providing Policy-Based Access Control, loosely based on XACML.

Before you start, you’ll need to have the following installed:

• Java 9+ (Site is not compatible with Java 8 and below!)

• Clojure and

• Babashka installed on your system.

macOS (>= 10.15)

$ brew install openssl
$ echo export JAVA_HOME=/usr/local/Cellar/openjdk/17.0.2/libexec/openjdk.jdk/Contents/Home >> ~/.zshrc
$ exec zsh -l

$ cd site # (if needed)
$ clojure -A:dev -M:test -m kaocha.runner --focus juxt.site.authz-test

$ ...
$ ... WARNING: ${JAVA_HOME}/bin/java is loading libcrypto in an unsafe way

$ ln -s  /usr/local/Cellar/openssl@3/3.0.1/lib/libcrypto.dylib $JAVA_HOME/lib

There’s a sample configuration in etc you should copy to $HOME/.config/site/config.edn.

Start the Site server:

If you require multiple Site servers to coexist on the same machine, you can start site passing a different configuration file as follows:

In this case please be sure to change the configuration so ports are different and XTDB files are stored in a separate folder than the ones specified in the example configuration file. You’ll also need to specify Site host:port when using site commands, for example:

Optionally, you can also get Site up and running using the provided Docker image. You need Docker installed in your system, then execute the following from the command line (sudo might not be necessary depending on your installation):

If you’ve run Site via your development environment and 'jacked-in' you’ll already have a REPL. Proceed to the next step.

If you’re running Site with site/bin/site-server, you’ll need to connect a terminal to Site to access the REPL. You can do this via port 50505, which is a socket REPL that Site starts by default.

How you connect to this port is up to you. One way is via ncat, but you can replace ncat with telnet, or netcat, depending on what’s available for your system.

Bootstrap the new system by adding the minimum resources that are required to allow remote access.

Install the Site API:

Install the authentication rules:

Install the superuser role:

Finally, create a superuser. If you have pass installed, this will fetch the password directly:

If you don’t have pass installed, you can add a password as a final argument to put-superuser!.

Replace "admin", "Administrator" and "admin" with your own username, full name and password respectively.

Quit the REPL, for example, with Ctrl-C or by typing :repl/quit.

The site tool is a command-line utility that allows you to remotely administer site.

If you’re on MacOS, you will need to install the gnu version of readlink. You can do so with brew:

We must first get a token that we can use for API access. This process authenticates to the site server using your password.

Now we can use the site tool for remote administration. Try the following:

(put! (assoc (e "http://localhost:2021/_site/token")  ::pass/expires-in (* 24 3600)))