Adding API Routes

Overview

Every API route in folksbase follows the same pattern: a Hono route handler with OpenAPI documentation via hono-openapi, request validation via Zod, and strict adherence to the layered architecture (Routes → Services → Repositories → Drizzle). This guide walks through adding a new route from scratch.

The Layered Architecture

Before writing any route code, understand the layers:

Layer	Responsibility	Location
Route	HTTP concerns only — parse request, call service, return response	`src/routes/*.ts`
Service	Business logic, orchestration, validation	`src/services/*.ts`
Repository	SQL queries only, no business logic	`src/repositories/*.ts`

Hard rules:

Routes never import from @folksbase/db
Services never construct HTTP responses
Repositories never contain business logic

Step 1: Define Your Zod Schemas

Start with the request and response schemas. If they’re reusable, add them to apps/api/src/lib/openapi-schemas.ts. Otherwise, define them in the route file.

import { z } from "zod";

const createBodySchema = z.object({
  name: z.string().min(1).max(100),
  color: z.string().max(20).optional(),
});

const updateBodySchema = createBodySchema.partial();

Step 2: Create the Route File

Create a new file in apps/api/src/routes/. Import the OpenAPI helpers and auth middleware:

import { errorSchema } from "@/lib/openapi-schemas.js";
import { type Variables, auth } from "@/middleware/auth.js";
import { Hono } from "hono";
import { describeRoute, resolver, validator as zValidator } from "hono-openapi";
import { z } from "zod";

Step 3: Add Route Handlers with OpenAPI Docs

Every route must use describeRoute() for response documentation and zValidator() for request validation:

export const widgetsRoute = new Hono<{ Variables: Variables }>()
  .use("*", auth)

  .get(
    "/",
    describeRoute({
      tags: ["Widgets"],
      summary: "List widgets",
      description: "Returns all widgets for the workspace.",
      responses: {
        200: {
          description: "Widget list",
          content: {
            "application/json": {
              schema: resolver(z.array(widgetSchema)),
            },
          },
        },
      },
    }),
    async (c) => {
      const { workspaceId } = c.get("user");
      const widgets = await widgetsService.findAll(workspaceId);
      return c.json(widgets);
    },
  )

  .post(
    "/",
    describeRoute({
      tags: ["Widgets"],
      summary: "Create widget",
      responses: {
        201: {
          description: "Widget created",
          content: {
            "application/json": { schema: resolver(widgetSchema) },
          },
        },
        400: {
          description: "Validation error",
          content: {
            "application/json": { schema: resolver(errorSchema) },
          },
        },
      },
    }),
    zValidator("json", createBodySchema),
    async (c) => {
      const { workspaceId } = c.get("user");
      const body = c.req.valid("json");
      const widget = await widgetsService.create(workspaceId, body);
      return c.json(widget, 201);
    },
  );

Key Patterns

Path params use zValidator("param", schema) — always enforce UUID format:
zValidator("param", z.object({ id: z.string().uuid() }))
Query params use zValidator("query", schema)
JSON body uses zValidator("json", schema)
Access validated data via c.req.valid("query"), c.req.valid("json"), or c.req.valid("param")

Step 4: Register the Route

Add your route to apps/api/src/index.ts:

import { widgetsRoute } from "@/routes/widgets.js";

// Inside the app setup
app.route("/api/widgets", widgetsRoute);

Step 5: Error Handling

Don’t add manual try/catch blocks in route handlers. Let errors propagate to the global errorHandler middleware, which handles ZodError and auth errors automatically and returns consistent { code, message } responses. The only exception is when you need to return a specific 404:

const widget = await widgetsService.findById(workspaceId, id);
if (!widget) {
  return c.json({ code: "NOT_FOUND", message: "Widget not found" }, 404);
}

Step 6: Verify

After adding your route:

Start the dev server: pnpm --filter @folksbase/api dev
Open http://localhost:3001/api/docs — your new route should appear in the Scalar UI
Check the OpenAPI spec at http://localhost:3001/api/openapi.json
Write unit tests in src/routes/__tests__/ following the existing patterns

Checklist

Before submitting your PR, verify:

Route uses describeRoute() with tags, summary, and response schemas
Request validation uses zValidator() (not manual .parse())
Route only calls services — no direct DB imports
Path params enforce UUID format where applicable
No manual try/catch — errors propagate to global handler
Unit tests use valid UUIDs for path parameters
Route is registered in src/index.ts

Getting Started

Features

Architecture

Background Jobs

API

Deployment

Contributing

Overview

The Layered Architecture

Step 1: Define Your Zod Schemas

Step 2: Create the Route File

Step 3: Add Route Handlers with OpenAPI Docs

Key Patterns

Step 4: Register the Route

Step 5: Error Handling

Step 6: Verify

Checklist

​Overview

​The Layered Architecture

​Step 1: Define Your Zod Schemas

​Step 2: Create the Route File

​Step 3: Add Route Handlers with OpenAPI Docs

​Key Patterns

​Step 4: Register the Route

​Step 5: Error Handling

​Step 6: Verify

​Checklist

Overview

The Layered Architecture

Step 1: Define Your Zod Schemas

Step 2: Create the Route File

Step 3: Add Route Handlers with OpenAPI Docs

Key Patterns

Step 4: Register the Route

Step 5: Error Handling

Step 6: Verify

Checklist