api-design.md

HTTP API design

• Contract — Prefer an explicit contract (OpenAPI or equivalent) before wide client use; keep it in sync with implementation.
• Errors — Stable machine-readable code (or similar); human message; include requestId where available. Avoid leaking stack traces to clients.
• Pagination — Cursor + limit; document max limit; return nextCursor or page metadata consistently.
• Idempotency — POST that allocates or charges: support idempotency keys or dedupe strategy; document behavior.
• Versioning — Prefer URL prefix (/v1/...) or clear deprecation policy; avoid silent breaking changes.
• Validation — Validate at the boundary; reject with 400 + structured field errors when helpful.

Handlers at the HTTP boundary

When editing route/view/handler entrypoints (paths depend on framework—e.g. **/routes/**, **/handlers/**, **/controllers/**, **/views/**, **/api/**):

• Prefer explicit validation and clear request/response shapes at the edge.
• Keep behavior aligned with the contract bullets above.

Related skills

• openapi-contract-node — Contract-first workflow in this pack (Node-oriented; mirror the same steps on other stacks).
• api-breaking-change — When contracts or clients must move together.
• release-readiness — API and operational readiness before ship.