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/statusWhat 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).inputholdsbody,queryandheadersvalidated byschema,paramfrom the[id:int]folder, anduser, the caller.cis the Hono context, forc.status(201)and headers.schema(optional):body,query,headersas zod objects;summary,tagsfor a custom label. Never declareparam, manh.run adds it.access(optional):"public"(anyone),"user"(signed in) or a role list like["admin", "manager"].rateLimit(optional): writes withaccess = "public"are limited by default to 30 requests per 10 minutes per IP and route; over that the app answers 429RATE_LIMITED.{ max: 5, windowSec: 60 }changes the limit,falseturns it off (webhooks from another system). GET is never limited.cache(GET only, optional):{ maxAge: 30, scope: "user" }, seconds from 1 to 300;scopeis"user"or"public".
Return values
| Returned | Status |
|---|---|
| object, array, number, boolean | 200, JSON |
| string | 200, text |
null or undefined | 204 |
Response | as is |
| wrong role or not signed in | 403 or 401, checked before schema |
schema mismatch | 400 |
fail(status, message, code) | that status, body { error, message, code } |
| any other error | 500, 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 numberThe 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")frommanh/errors. Returningc.json({ error }, 404)loses the standard body the UI expects. accessdefaults to"user"when the app hasapp/auth.ts; otherwise nothing is checked. Not signed in gets 401, wrong role gets 403.- Calling
db.*straight from a handler warnscode.no-inline-drizzle-in-handler. Database calls belong inrepository.ts. cacheon a GET that writes or sends mail warnscache.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.tsorpatch.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 —
schemakeys,access, caching and the generated client. - repository.ts — where the database calls and business rules a handler calls live.
- middleware.ts — set
accessfor a whole folder.
Last updated