Skip to main content

Developer Workflow

This page outlines how development with Minimal works from setup to production.

Phase 1 — Setup (Once)​

Done by DevOps or an admin. Happens once per product.

  1. Deploy Minimal on your server
  2. Configure config.yml — server key, database defaults
  3. Set up your gateway — JWT validation, header injection into Minimal
  4. Create your organization → get org_id
  5. Create your project → get project_id and three spaces — dev, staging, prod

After this, Minimal is live and ready to accept requests.

Phase 2 — Auto API​

No code required. As soon as Minimal is pointed at your database, every table has four live endpoints:

GET    /minimal/api/rest/auto/v1/{org_abbr}/{project_abbr}/{db_type}/{db_name}/{table}   — list rows
POST   /minimal/api/rest/auto/v1/{org_abbr}/{project_abbr}/{db_type}/{db_name}/{table}   — create row
PUT    /minimal/api/rest/auto/v1/{org_abbr}/{project_abbr}/{db_type}/{db_name}/{table}   — update row
DELETE /minimal/api/rest/auto/v1/{org_abbr}/{project_abbr}/{db_type}/{db_name}/{table}   — delete row

Use Auto API for standard CRUD — dashboards, admin panels, simple data operations.

Phase 3 — Custom API​

When Auto API isn't enough — JOINs, transformations, multi-step logic — write a YAML definition.

  1. Write the YAML definition locally
  2. Generate a new feature_id (ULID)
  3. Deploy to dev space — POST /minimal/rest/definition/v1
  4. Call the endpoint with ?version=0.1
  5. Iterate — update with PUT, bump http.version each time
  6. When ready — promote to staging and production via space/copy

Phase 4 — Promote to Production​

dev space       → build and test
      ↓
staging space   → QA and sign off
      ↓
production      → live, zero restart

Promotion is a single API call — pass a list of definition_id values and a target space. Minimal copies them instantly.

Day-to-Day Loop​

Write YAML
  → deploy to dev
  → call endpoint
  → tweak, bump version, redeploy
  → copy to staging → production

What You Don't Write​

TraditionalWith Minimal
Route handlers❌ Not needed
ORM models❌ Not needed
Auth middleware❌ Handled by gateway
Server restart on new endpoint❌ Not needed

The only code you write is SQL inside a YAML file — and optionally Starlark or Expr for data transformation.