Excalibase REST
Every table your API permissions expose is a REST resource. No controllers, no DTOs: add a table
in Studio or with SQL and GET /api/v1/{table} answers a few seconds later. The same engine and the
same permissions answer GraphQL; pick whichever fits the call.
On Excalibase Cloud
Every route starts with your project id. First connect and exchange a key for a token,
then send it as Authorization: Bearer $TOKEN:
| Route | What it does |
|---|---|
GET /{projectId}/api/v1/{table} | List rows: filter, sort, paginate, pick columns |
POST /{projectId}/api/v1/{table} | Insert a row, or an array of rows |
PATCH /{projectId}/api/v1/{table}?col=eq.value | Update the rows a filter matches |
PUT /{projectId}/api/v1/{table}?col=eq.value | Replace the rows a filter matches |
DELETE /{projectId}/api/v1/{table}?col=eq.value | Delete the rows a filter matches |
GET or POST /{projectId}/api/v1/rpc/{function} | Call a tracked function |
GET /{projectId}/api/v1 with Accept: application/openapi+json | The OpenAPI 3 document for what your role can reach |
curl -s "$BASE/$PROJECT_ID/api/v1/feedback_posts?select=id,kind,body&order=id.desc&limit=2" \
-H "Authorization: Bearer $TOKEN"
A single row is a filter, not a path: ?id=eq.1. There is no /{table}/{id} route.
Which tables, columns and rows a caller reaches is decided by the API permissions
of the role in their token. A request with no token runs as anon.
curl -s "$BASE/$PROJECT_ID/api/v1" -H "Accept: application/openapi+json" | jq '.paths | keys'
Import that document into Swagger UI, Postman or Insomnia.
What you get
- Filter operators:
eq,gt,ilike,in,is.null, JSON and array operators, full-text search. See Filtering. - Column selection:
?select=id,kind. - Ordering and pagination:
order=id.desc,limitandoffset, or aRangeheader.Prefer: count=exactadds a total where your role may count. - Writes with a dry run:
Prefer: tx=rollbackruns the statement and rolls it back. - Exact numbers: bigint and decimal columns arrive as strings (
"19.90"), and are taken back as a string or a number. See Numbers. - Typed errors: 409 for a duplicate, 400 for a bad reference or value, 403 for a refused permission, each with a
code. See Errors.
Aggregations and nested relationships are GraphQL features. See Aggregations and Relationships for the GraphQL form, and Subscriptions for realtime.
Self-hosting
This section is for running the engine yourself.
- A standalone engine serves the same
/{projectId}/api/v1/{table}routes; the quick start below gives the local ports. - The standalone
excalibase-restservice (the separate repository) also serves routes a cloud project does not:GET /api/v1/{table}/{id},GET /api/v1/{table}/{id1},{id2}for composite keys,/api/v1/openapi.jsonand/api/v1/openapi.yaml, an SSE stream at/api/v1/{table}/changesand a WebSocket at/ws/{table}/changes. These answer 404 on Excalibase Cloud. The replacements there are?id=eq.1, theAccept: application/openapi+jsonrequest above, and GraphQL subscriptions.
| Database | Status |
|---|---|
| PostgreSQL | Supported (PG 15+) |
| MySQL | Supported |
| Oracle | Planned |
github.com/excalibase/excalibase-graphql: REST and GraphQL ship from the same engine.