clj-rest-api

An example REST API based on Pedestal & Duct.

This project shares the data models with lagenorhynque/aqoursql, an example GraphQL API.

Developing

Prerequisites

• Java (JDK)
  • java --version >= 11
• Leiningen
• Docker

Setup

When you first clone this repository, run:

$ lein duct setup

This will create files for local configuration, and prep your system for the project.

Database

# Start local DB
$ docker compose up -d
# Import DB schema
$ docker compose exec -T mariadb mariadb -uroot -proot aqoursql < sql/ddl/aqoursql.sql
$ docker compose exec -T mariadb-test mariadb -uroot -proot aqoursql_test < sql/ddl/aqoursql.sql
# Seed DB
$ docker compose exec -T mariadb mariadb -uroot -proot aqoursql < sql/dml/seed.sql

Development environment

To begin developing, start with a REPL.

$ lein repl

With rebel-readline:

$ lein rebel

Then load the development environment.

user=> (dev)
:loaded

Run go to prep and initiate the system.

dev=> (go)
:duct.server.http.jetty/starting-server {:port 9999}
:initiated

By default this creates a web server at http://localhost:9999.

When you make changes to your source files, use reset to reload any modified files and reset the server.

dev=> (reset)
:reloading (...)
:resumed

Run halt to halt the system.

dev=> (halt)
:halted

Production build & run

$ lein uberjar
$ DATABASE_URL="..." java -jar target/clj-rest-api.jar

Testing

Testing is fastest through the REPL, as you avoid environment startup time.

dev=> (test)
...

But you can also run tests through Leiningen.

$ lein test

with cloverage:

$ lein test-coverage
# Open the coverage report
$ open target/coverage/index.html

Linting

• eastwood, kibit

$ lein lint

• cljstyle check, clj-kondo, joker

$ make lint

• fixing formatting

$ make cljstyle-fix

API Documentation (Codox)

$ lein codox
$ open target/codox/index.html