Production HTTP API

# Production HTTP API

An HTTP API with typed routes, generated docs, sane errors, and logs you can debug from - deployable to any runtime.

## Recommended stack

- **Hono** - framework. Runs on Node, Bun, Deno, and edge runtimes; zod-openapi middleware types every route.
- **Postgres** - data. Constraints, transactions, and 30 years of operational knowledge.
- **zod + @hono/zod-openapi** - contracts. Request/response schemas generate the OpenAPI spec - docs can't drift.
- **Structured logs (pino) + request ids** - observability. Every error traceable to one request id is the debugging baseline.

## Build steps

1. Design resources and error shape first: `{ error, code, request_id }` on every non-2xx.
2. Define zod schemas per route; mount the generated OpenAPI doc at /doc and Swagger UI at /ui.
3. Add middleware order: request-id → logger → auth → rate limit → handler.
4. Use transactions at the service layer; return 409/422 for constraint violations, never 500.
5. Ship a /health endpoint and one happy-path integration test per resource before launch.

## Watch out for

- Leaking stack traces in error responses.
- Pagination as an afterthought - cursor-paginate list endpoints from day one.
- Auth in handlers instead of middleware: one forgotten route is a breach.

## Definition of done

- OpenAPI doc matches behavior because it's generated from the same schemas
- P95 latency and error rate visible on one dashboard
- A new client can integrate from /ui without asking questions