Getting started

Ten minutes from nothing to an API answering requests.

What you need

An OCI engine — podman or docker — and the three repositories checked out beside each other:

runtime/      the interpreter
deployment/   how it is run
app/          an example application

Start everything

cd deployment
make serve     # builds the runtime image, starts Postgres and the runtime
make apply     # creates the tables from ../app/northwind

make serve before make apply is not a mistake — it is worth seeing what the runtime does when the database has no schema yet:

$ curl "localhost:9090/readyz?verbose"
[+] ping ok
[+] database ok
[-] model failed: this database was provisioned from a different model; run `runtime db apply`
readyz check failed

Readiness refuses traffic and names the fix. Liveness stays 200, because restarting would not create the schema — it would only add a cold start. That distinction is the whole reason there are two probes.

Ask it something

$ curl localhost:8080/api/v1/sales/Customer
{"data":[],"next":null}

$ curl localhost:8080/api-doc/openapi.json

The OpenAPI document is generated for the credentials you presented. Entities and fields your token cannot reach are absent from it — so it answers “what can I do”, not “what exists”.

Change the model

Open app/northwind/modules/sales/security.yaml and give the Guest role something new. Then, without restarting anything:

$ curl -X POST localhost:9090/_admin/model/reload
{"outcome":"reloaded","model":"northwind","version":"0.1.0","flows":1}

The next request uses the new policy. That is the interpreter premise paying off: changing an application is an edit and a reload, not a build and a deploy.

Try changing domain.yaml instead — adding an attribute, say — and the reload refuses:

{
  "outcome": "schema-changed",
  "detail": "this model implies a different database schema…"
}

Reload swaps what needs no migration. A schema change is runtime db apply, and it stays that way on purpose.

Break it on purpose

The error messages are the product, so it is worth seeing one. Put a precision on a string attribute:

$ runtime model validate app/northwind
error[M203]: `precision` is not a parameter of type `string`
  --> modules/sales/domain.yaml (entities[0].attributes[1])
  help: remove it, or change the type to `decimal`

Every diagnostic has a stable code, a location, and — where there is an answer — what to write instead.

Your first application — build one from scratch.
Runtime — the reference for each part of a model.

Keyboard shortcuts