Bring Your Own API Framework

MooseStack provides flexible approaches for building HTTP APIs to expose your data. You can use Moose’s built-in Api class for simple GET endpoints, or bring popular web frameworks like Express, Koa, Fastify, or FastAPI for advanced features and custom middleware.

These framework integrations give you two complementary integration paths:

• Embed supported frameworks inside your MooseStack project. Mount Express, Koa, Fastify, or raw Node.js with WebApp so MooseStack deploys everything together and injects auth, client, and sql helpers on every request.
• Call MooseStack from any framework using the client. Keep an existing app (Next.js, Rails, etc.) in its current runtime and use the MooseStack TypeScript or Python client to query ClickHouse or trigger workflows.

Overview

Native APIs

Moose’s built-in Api class provides simple GET endpoints with automatic type validation and OpenAPI documentation. This is ideal for straightforward data queries without complex routing or middleware requirements.

Use Native Api class when you need:

• Simple GET endpoints with query parameters
• Automatic type validation and conversion
• Automatic OpenAPI documentation generation
• Minimal setup and boilerplate

Embed a supported framework inside a MooseStack project

Use the WebApp class to mount your framework in your MooseStack project alongside tables, streams, and workflows.

Why embed the framework:

• One deployment pipeline managed by the MooseStack CLI (dev hot reload + production config)
• Access MooseStack utilities (client, sql, jwt) in every handler through getMooseUtils
• Optionally share auth, logging, and observability defaults with the rest of your MooseStack modules
• Compose MooseStack APIs and framework routes under the same hostname

Use the MooseStack client from any framework

If you already have an application server, call MooseStack directly with the client SDKs—no MooseStack deployment required. Works great for Next.js, Rails, Python microservices, or anything else that can make HTTP requests.

Here’s the client pattern:

import { MooseClient, sql } from "@514labs/moose-lib";
import { UserTable } from "./tables/UserTable";
 
const client = new MooseClient();
 
export async function listUsers(limit = 25) {
  const result = await client.query.execute(
    sql`
      SELECT 
        ${UserTable.columns.id}, 
        ${UserTable.columns.name}, 
        ${UserTable.columns.email}
      FROM ${UserTable}
      WHERE ${UserTable.columns.status} = 'active'
      LIMIT ${limit}
    `
  );
  return await result.json();
}

from moose_lib import MooseClient
from app.tables.user_table import UserTable
 
client = MooseClient()
 
def list_users(limit: int = 25):
    query = f"""
        SELECT 
          {UserTable.columns.id}, 
          {UserTable.columns.name}, 
          {UserTable.columns.email}
        FROM {UserTable}
        WHERE {UserTable.columns.status} = 'active'
        LIMIT {{limit:UInt32}}
    """
    return client.query.execute_raw(query, {"limit": limit})

Supported Frameworks

TypeScript

Python

Key Concepts

WebApp Class

The WebApp class is the bridge between your web framework and MooseStack. It handles:

• Mounting your framework at a custom URL path
• Injecting MooseStack utilities (database clients, SQL helpers, JWT)
• Validating JWT tokens when authentication is configured
• Managing the request/response lifecycle

Accessing Data

All frameworks can access your OLAP database through MooseStack’s injected utilities:

import { getMooseUtils } from "@514labs/moose-lib";
 
const moose = getMooseUtils(req);
const { client, sql, jwt } = moose;

from moose_lib.dmv2.web_app_helpers import get_moose_utils
 
moose = get_moose_utils(request)
client = moose.client
jwt = moose.jwt

Mount Paths

Each WebApp must specify a unique mount path where it will be accessible. Mount paths have specific rules:

• Cannot be / (root path)
• Cannot end with a trailing slash
• Cannot start with reserved paths: /admin, /api, /consumption, /health, /ingest, /mcp, /moose, /ready, /workflows

Valid: /myapi, /v1/analytics, /custom/endpoint

Invalid: /, /myapi/, /api/myendpoint