---
name: api-design
description: Designing REST/HTTP endpoints + contracts. Triggers on design-api/endpoint/REST/OpenAPI/route.
---
# api-design (node-ts)

resource nouns, HTTP verbs. consistent status codes. version from day one.

- validate input at the boundary with a schema (zod/valibot) — reject early, derive the type from the schema.
- async handlers: `await` + a central error middleware; never leak stack traces to clients.
- stable contracts — additive changes only. document request/response shape (OpenAPI).
- paginate list endpoints (limit/cursor). explicit status codes: 201 create, 204 no-content, 422 validation.
- no secrets in responses. auth + CORS checked per route.