Api design

Skill jagreehal/jagreehal-claude-skills/skills/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.From its SKILL.md

Install

npx -y skills add jagreehal/jagreehal-claude-skills --skill api-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

3 stars3 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.5 KB, as published. Nobody here has run it

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.