# API Design

> Builds production-ready HTTP APIs with thin handlers, consistent error envelopes, health checks, CORS, idempotency, rate limiting, and graceful shutdown. Use this skill when designing or implementing HTTP endpoints, orpc routes, Zod request/response schemas, or mapping domain errors to status codes. Do not use when/for pure domain logic without HTTP (use fn-args-deps and result-types) or frontend data fetching alone.

- Skill: `jagreehal/api-design` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add jagreehal/api-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jagreehal/api-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: jagreehal (https://skillmd.com/u/jagreehal)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jagreehal/api-design

---


# API Design Patterns

## Critical rules

- Handlers only translate HTTP ↔ domain: validate at the edge, call `fn(args, deps)` / Result, map to response. No business logic in handlers.
- One error envelope everywhere; `ORPCError(code)` must match `ErrorResponse.code`.
- Shared domain-error → status mapping; `/health` and `/ready`; `X-Request-ID` in middleware once.
- Mutations require `Idempotency-Key`; 429 includes `Retry-After`; drain with 503 on shutdown.
- One file per route with co-located tests; compose routers via factories.
- Before implementing routes or ops concerns, read [references/patterns.md](references/patterns.md).

## Workflow

1. Define Zod input/output schemas at the framework boundary.
2. Create a route factory `createX({ deps })` that delegates to domain functions.
3. Map domain errors through the shared status table and consistent envelope.
4. Add health/ready, CORS, request ID middleware, idempotency, rate limits, shutdown — see [references/patterns.md](references/patterns.md).
5. Compose routers at module boundaries (`createPostsRouter` → `createApiRouter`).
6. Write co-located tests with `call()` — see [references/testing.md](references/testing.md).

## Resources

- [references/patterns.md](references/patterns.md) — factories, errors, health, CORS, idempotency, organization. Read when designing endpoints.
- [references/testing.md](references/testing.md) — route unit tests with mocked deps. Read when writing route tests.

## Validation

- [ ] Routes are factories with injected deps; handlers stay thin
- [ ] Errors use one envelope; codes match
- [ ] Shared status mapping; `/health` and `/ready` exist
- [ ] Mutations honor Idempotency-Key; 429 has Retry-After; shutdown → 503
- [ ] X-Request-ID set in middleware
- [ ] Co-located success and error tests per route

## Constraints

- Internal calls and background jobs without HTTP are out of scope. Retry policy belongs in `resilience`.
- Related: `fn-args-deps`, `validation-boundary`, `result-types`, `resilience`, `observability`.