REST Quick Start

Docker (recommended)

git clone https://github.com/excalibase/excalibase-rest.git
cd excalibase-rest
cp .env.example .env
# Edit .env with your database credentials
docker-compose up -d

API runs on port 20000 by default.

Configuration

application.yaml

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/yourdb
    username: youruser
    password: yourpass

app:
  allowed-schema: public
  max-page-size: 1000
  default-page-size: 100

Configuration reference

Key	Default	Description
`app.allowed-schema`	`public`	PostgreSQL schema to expose
`app.default-page-size`	`100`	Rows returned when no `limit` is specified
`app.max-page-size`	`1000`	Maximum rows per request
`server.port`	`20000`	HTTP port
`app.nats.enabled`	`false`	Enable CDC real-time subscriptions (SSE + WebSocket)
`app.nats.url`	`nats://localhost:4222`	NATS server URL (requires JetStream)
`app.nats.stream-name`	`cdc-stream`	NATS JetStream stream name

Environment variables

SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/yourdb
SPRING_DATASOURCE_USERNAME=youruser
SPRING_DATASOURCE_PASSWORD=yourpass
APP_ALLOWED_SCHEMA=public
APP_NATS_ENABLED=true
APP_NATS_URL=nats://localhost:4222

CRUD examples

List with filter

curl "http://localhost:20000/api/v1/film?rating=eq.PG&limit=10"

Get by primary key

curl http://localhost:20000/api/v1/film/1

Create

curl -X POST http://localhost:20000/api/v1/film \
  -H "Content-Type: application/json" \
  -d '{"title": "My Film", "rental_rate": 2.99, "rental_duration": 7, "replacement_cost": 14.99, "language_id": 1}'

Full update (PUT)

Replaces the entire row. Any fields not provided are set to their default or NULL.

curl -X PUT http://localhost:20000/api/v1/film/1001 \
  -H "Content-Type: application/json" \
  -d '{"title": "My Film Updated", "rental_rate": 1.99, "rental_duration": 5, "replacement_cost": 14.99, "language_id": 1}'

Partial update (PATCH)

Updates only the fields you provide. Other columns are untouched.

curl -X PATCH http://localhost:20000/api/v1/film/1001 \
  -H "Content-Type: application/json" \
  -d '{"rental_rate": 0.99}'

Delete

curl -X DELETE http://localhost:20000/api/v1/film/1001

Composite primary key

For tables with composite keys (e.g. film_actor with film_id, actor_id):

curl http://localhost:20000/api/v1/film_actor/1,10

OpenAPI Docs

Once running, your full API spec is available at:

JSON: http://localhost:20000/api/v1/openapi.json
YAML: http://localhost:20000/api/v1/openapi.yaml

Import into Swagger UI, Postman, or Insomnia. Every endpoint, every parameter, every response shape is documented automatically from your live schema.

Maven

mvn clean install
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/yourdb
export SPRING_DATASOURCE_USERNAME=youruser
export SPRING_DATASOURCE_PASSWORD=yourpass
mvn spring-boot:run

Introduction

Filtering