HTTP server

Build a REST API

A full CRUD API — routes, auth, validation, pagination, a real database — in one file, with the production HTTP server built in. No framework, no ASGI server, no requirements.txt.

The whole thing§

require serve(8080)
require db("./store.db")

db_open("./store.db")   -- `require db` grants the capability; `db_open` opens the connection

task check_token(token)   -- the auth task receives the bearer token (stripped), not the request
    give when token == "secret" then {"user": "admin"} otherwise nothing   -- give an identity to allow, `nothing` to reject (401)

serve on 8080
    auth with check_token

    route "GET /products"
        give paged("SELECT id, name, price FROM products ORDER BY id")   -- paginated + total

    route "GET /products/:id"
        let rows be sql("SELECT * FROM products WHERE id = ?", [params.id])
        give when length(rows) == 0 then not_found("no such product") otherwise rows[0]

    route "POST /products" requires auth
        expect body {name: text, price: number}      -- 400 automatically if it doesn't match
        let b be json of request
        sql_exec("INSERT INTO products (name, price) VALUES (?, ?)", [b["name"], b["price"]])
        give created(b)

    route "DELETE /products/:id" requires auth
        sql_exec("DELETE FROM products WHERE id = ?", [params.id])
        give ok({"deleted": params.id})

Run it: synsema serve api.syn. That's a production server — async, true multi-core, a single static binary with zero runtime.

What you got for free§

-- Doc example: the serve response contract. Helpers return {status, value}; the
-- runtime renders them. (A real `serve on` block doesn't terminate, so the doctest
-- asserts the response shapes the handlers give — see the prose for a full server.)
intent: "doc example: serve response contract"

print("ok → " + text(status of ok({"a": 1})) + ",  fail(400) → " + text(status of fail(400, "bad")))

test "uniform response helpers carry a status + value"
    assert_eq(status of ok({"a": 1}), 200)
    assert_eq(status of created({"id": 1}), 201)
    assert_eq(status of fail(400, "bad input"), 400)
    assert_eq(status of not_found("missing"), 404)
    assert_eq((value of fail(400, "bad input"))["error"], "bad input")

• Uniform responses — ok/created/fail/not_found carry the right status; a bare value becomes 200 {json}.
• Validation — expect body {…} returns 400 with detail when the body doesn't match; no manual checks.
• Auth — auth with <task> + requires auth per route.
• Pagination — paged(...) pushes LIMIT/OFFSET into SQL and computes an exact total.
• Secure by default — require db/serve, secrets redacted, capability-scoped.

Your API already has OpenAPI and /docs§

Nothing to add. With the routes above the server already serves /openapi.json (OpenAPI 3.1 derived from route + expect + requires auth + rate_limit, with x-synsema-capabilities saying what each operation may touch) and /docs — a page to browse and try every operation from the browser; an agent that sends Accept: text/markdown gets the same reference as Markdown. Name the version with describe version: "1.0.0". In CI, synsema openapi app.syn --out openapi.json writes the same document without starting anything: the spec is a build artifact of the source, never a second thing to maintain. Details and limits (no response schema, sitemap without parametric routes): Discovery.

vs. FastAPI§

No framework to install, no Pydantic models, no Uvicorn, no requirements.txt — one binary, one file. Validation and auth are language keywords, not decorators you wire up by hand. @app.post + a Pydantic model ↔ route "POST /x" + expect body {…}; /docs ↔ /docs; app.openapi() ↔ synsema openapi app.syn. And it's secure by default and deployed with one flag. See HTTP server for the full route/SSE/CORS reference and Frontend to also serve HTML.