Moose APIs & Web Apps
MooseStack lets you expose HTTP endpoints for ingestion, analytics, and workflow triggers.
You can do this in two distinct ways:
- Native Moose APIs: define endpoints with Moose primitives (type-safe, OpenAPI-friendly).
- Web apps inside the Moose Runtime: run Express/Fastify/Koa/FastAPI (or raw Node) inside MooseStack via
WebApp.
If you want to embed Moose as a library inside an existing web app (no separate Moose Runtime service), follow the “Add to Existing App” guides like Next.js or Fastify.
What this is
Moose APIs are application-facing HTTP interfaces that sit on top of your Moose modules (OLAP tables, streams, workflows). They’re designed to be composed with the rest of your project, not used in isolation.
Why it matters
APIs are where external systems interface with your OLAP database. MooseStack gives you a path that is:
- Type-safe: validate and convert request inputs.
- Operationally simple: one runtime + one deployment when Moose hosts your web app.
- Composable: reuse the same
client/sqlaccess patterns across handlers.
Choose an approach
| You want… | Use… |
|---|---|
| Fastest path to ingestion/analytics endpoints | Native Moose APIs |
| Custom middleware/routing, but still want Moose to run your web server | WebApp (inside Moose Runtime) |
| Typed ClickHouse models + queries in your existing backend runtime | Embed MooseStack in an existing app (e.g. Fastify) |
1) Native Moose APIs
Native APIs are best for straightforward endpoints with minimal routing/middleware needs.
- Ingest API: create POST endpoints that validate payloads and route them into streams/tables.
- Analytics API: create GET endpoints that run queries (OLAP or custom logic).
- Trigger API: create POST endpoints that kick off workflows.
2) Web apps inside the Moose Runtime (WebApp)
If you want a full-featured web framework, MooseStack can host it via WebApp as part of the Moose Runtime.
Why embed your framework:
- One deployment pipeline managed by the Moose CLI
- Moose utilities available in every request (
client,sql,jwt) - Moose APIs and your framework routes can live under the same hostname
Supported adapters include: Express, Fastify, Koa, raw Node.js, and FastAPI.
3) Use Moose CLI + library in your existing backend
If you already have an app server (like Next.js or Fastify), you can keep it where it is and use Moose as a CLI tool (for schema migrations) and library (for type-safe ClickHouse queries) without deploying a separate Moose Runtime web service.
Next steps
Don’t conflate WebApp with client-only embedding
WebApp runs your API framework inside the Moose Runtime. Client-only embedding keeps your existing app server and uses Moose as a library (see Next.js).