Skip to Content

get.ts, post.ts, put.ts, patch.ts, delete.ts

Each get.ts, post.ts, put.ts, patch.ts or delete.ts file is an API endpoint for that method, at the path of its folder.

app/orders/ ├── get.ts # GET /api/orders ├── post.ts # POST /api/orders ├── stats/ │ └── get.ts # GET /api/orders/stats └── [id:int]/ ├── get.ts # GET /api/orders/:id ├── patch.ts # PATCH /api/orders/:id ├── delete.ts # DELETE /api/orders/:id └── status/ └── post.ts # POST /api/orders/:id/status

What it does

The file name is the method, in lowercase. A handler runs on the server, gets validated input, calls one function in repository.ts and returns the result. Handlers are served under /api on the app’s domain.

Exports

  • default: a function (c, input). input holds body, query and headers validated by schema, param from the [id:int] folder, and user, the caller. c is the Hono context, for c.status(201) and headers.
  • schema (optional): body, query, headers as zod objects; summary, tags for a custom label. Never declare param, manh.run adds it.
  • access (optional): "public" (anyone), "user" (signed in) or a role list like ["admin", "manager"].
  • rateLimit (optional): writes with access = "public" are limited by default to 30 requests per 10 minutes per IP and route; over that the app answers 429 RATE_LIMITED. { max: 5, windowSec: 60 } changes the limit, false turns it off (webhooks from another system). GET is never limited.
  • cache (GET only, optional): { maxAge: 30, scope: "user" }, seconds from 1 to 300; scope is "user" or "public".

Return values

ReturnedStatus
object, array, number, boolean200, JSON
string200, text
null or undefined204
Responseas is
wrong role or not signed in403 or 401, checked before schema
schema mismatch400
fail(status, message, code)that status, body { error, message, code }
any other error500, body { error: "INTERNAL", message: "Máy chủ gặp lỗi…" }, details only in the logs

Example

app/orders/post.ts
import { z } from "@hono/zod-openapi"; import { createOrder } from "./repository"; export const access = ["admin", "sales"]; export const schema = { body: z.object({ productId: z.number().int().positive(), quantity: z.number().int().min(1).max(100), customerName: z.string().min(1).max(200), }), }; export default async (c, { user, body }) => { c.status(201); return createOrder(user, body); };
app/orders/[id:int]/get.ts
import { getOrder } from "../repository"; export default (c, { user, param }) => getOrder(user, param.id); // param.id is already a number

The generated client names calls after the files: get.ts without an id is api.orders.list(), post.ts is api.orders.create(body), [id:int]/get.ts is api.orders.detail(id), [id:int]/status/post.ts is api.orders.status(id, body).

Good to know

  • Throw errors, don’t return them: fail(404, "Order not found", "NOT_FOUND") from manh/errors. Returning c.json({ error }, 404) loses the standard body the UI expects.
  • access defaults to "user" when the app has app/auth.ts; otherwise nothing is checked. Not signed in gets 401, wrong role gets 403.
  • Calling db.* straight from a handler warns code.no-inline-drizzle-in-handler. Database calls belong in repository.ts.
  • cache on a GET that writes or sends mail warns cache.side-effect: a cached hit skips the handler.
  • Every non-GET request clears the app’s cache before it runs.
  • Don’t branch on c.req.method. One method per file.
  • A GET only reads, and so do the functions it calls. Opening a page calls its GETs, so an UPDATE or DELETE there quietly changes or removes the owner’s records. Put the change in post.ts or patch.ts. Creating a missing default row on the first read is fine. manh.run writes a warning to the log when a GET changes data: [warn] GET /settings/setup changed table warehouses (UPDATE).

Next steps

  • API handlers — schema keys, access, caching and the generated client.
  • repository.ts — where the database calls and business rules a handler calls live.
  • middleware.ts — set access for a whole folder.
Last updated