Skip to content
VowVow Docs

HTTP API

Use case: health + hello JSON API

Section titled “Use case: health + hello JSON API”
Terminal window
curl -fsSL https://install.vowlang.dev | sh
vpm init my-api && cd my-api
vpm add vow-web-server@0.3.0
vpm install

Or scaffold with the web template:

Terminal window
vow create my-api --web
cd my-api && vpm install

Express → vow-web-server

Section titled “Express → vow-web-server”

Express

const express = require('express');
const app = express();
app.use(morgan('dev'));
app.get('/health', (req, res) => res.json({ ok: true }));
app.get('/hello', (req, res) => res.send('hello'));
app.listen(8787);

vow-web-server

import vws from vow_web_server
import json
import vow_web_server.request
import vow_web_server.response


fn health(_req: request.Request) -> response.Response {
    return vws.json(json.stringify({ ok: true }))
}


fn hello(_req: request.Request) -> response.Response {
    return vws.send("hello")
}


fn main(caps: Caps) -> int {
    let rt = vws.runtime(caps)
    var app = vws.server()
    app = vws.use_middleware(app, vws.logger())
    app = vws.get(app, "/health", health)
    app = vws.get(app, "/hello", hello)
    return vws.serve(app, rt, 8787)
}
Terminal window
vds
# or: vow run src/main.vow -- --grant net:
curl http://127.0.0.1:8787/health
curl http://127.0.0.1:8787/hello

Production daemon (after vpm add vow-serve -g):

Terminal window
vow-serve init && vow-serve start
vow-serve list

Handlers are fn(Request) -> Response. Register with get / post / put / delete / patch and reassign the handle each time. Path params: /users/:id → vws.param(req, "id"). JSON replies set Content-Type automatically.

Async database routes

Section titled “Async database routes”

Handlers stay sync. Put I/O in async fn helpers and call block_on:

async fn todo_count() -> int {
    let rows = await db_query(g_handle, "SELECT id FROM todos")?;
    return json_len(json.parse(rows)?)?;
}


fn api_health(_req: request.Request) -> response.Response {
    return vws.json(json.stringify({ todos: block_on(todo_count) }));
}

Full-stack demo with Postgres: hello-app/ · guide: Async / await · vow-postgres.

Versioned API with sub-router

Section titled “Versioned API with sub-router”

Express

const api = express.Router();
api.use(express.json());
api.get('/users', listUsers);
app.use('/api/v1', api);

vow-web-server

var app = vws.server()
app = vws.use_middleware(app, vws.logger())


var api = vws.router()
api = vws.use_middleware(api, vws.json_mw())
api = vws.get(api, "/users", list_users)
app = vws.use_middleware(app, "/api/v1", api)


return vws.serve(app, rt, 8787)

Full package docs: vow-web-server, vpm, ecosystem.

Packaged integration proof

Section titled “Packaged integration proof”

Tier-1 helpers (body-parser, cors, thin log/rbac/postgres DSN) wired as path deps:

Terminal window
cd vow-examples/vow-web-server/integration_rest
vpm install && ./e2e.sh
# runtime: vow run src/main.vow -- --grant net:

Monorepo without vpm

Section titled “Monorepo without vpm”
Terminal window
./vow run vow-examples/vow-web-server/http_api.vow -- --grant net:

After the tutorial

Section titled “After the tutorial”
  1. Language reference — Syntax
  2. Examples gallery
  3. Limitations
  4. Changelog