How do I install the API Design skill?

Run npx skillmds@latest add jagreehal/api-design in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is API Design safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with API Design?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is API Design free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published API Design?

jagreehal (@jagreehal) published this skill. Their other Agent Skills are listed on their SkillMD profile.

API Design by jagreehal — Agent Skill

Name: API Design
Rating: 4.2 (5 reviews)
Author: jagreehal

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.

jagreehal Updated Sep 10, 2026

File contents

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.

Workflow

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

Resources

references/patterns.md — factories, errors, health, CORS, idempotency, organization. Read when designing endpoints.
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.

---name: api-designdescription: 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.---# 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).## Workflow1. 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`.

Frequently asked questions